Admin GraphQL API / 2026-04

delegateAccessTokenCreate
expiresIn now returns

When creating a delegate token, the response now includes "how many seconds until expiration." In particular, when you omit the expiry and inherit the parent token's TTL, you can now determine the expiration time — something that was previously impossible to know.

On this page
  1. What changed (understand in 30 seconds)
  2. How it works: what the mutation returns alongside the token
  3. Where it especially helps: expiresIn omitted = parent TTL inherited
  4. Before vs. now
  5. Requirements
  6. 5 points engineers should know
  7. 3 use cases you can apply to your work
  8. One-line summary for proposals

1What changed

delegateAccessTokenCreate The mutation now returns DelegateAccessToken to the type expiresIn field added.
The value is "seconds remaining until expiration". With this, developers building apps that use delegate tokens can now precisely know when a token will expire.
? ? ?

Before: expiration time was unreadable

You could create the token, but the response carried no expiry information. Especially when no expiry was specified, there was no way to know when it would expire.

expiresIn

Now: remaining seconds are returned

The response's expiresIn now contains "how many seconds until expiration." This makes it possible to design refresh timing and add monitoring.

2How it works: what the mutation returns alongside the token

App Holds parent token Request delegation delegateAccessTokenCreate Issue delegate token With expiresIn input (optional), specify TTL or omit it mutation DelegateAccessToken (response) accessToken : shpat_... accessScopes : [...] expiresIn: 86399 ← new Seconds remaining Predict expiration
# Example mutation response (illustrative) { "delegateAccessToken": { "accessToken": "shpat_xxxxxxxx", "expiresIn": 86399 // Seconds remaining until expiration } }
What is a delegate token: a child token that an app issues by carving out a subset of permissions from its own parent token.expiresIn You can specify the TTL (time to live) in the input.What was newly added is the response-side expiresIn which represents "seconds remaining until expiration."(Specific schema details beyond the fields in the code above are not described in the article.)

3Case where it especially helps: expiresIn not specified = parent TTL inherited

What the article specifically calls out as "particularly beneficial" is thein the input expiresIn was not specifiedcase. In this case, the delegate token inherits the parent token's TTL (Time to Live).

A. When expiresIn is specified input expiresIn = 3600 TTL = specified value expiresIn ≒ 3600 Could roughly be inferred from the input value before → Now the confirmed value is available in the response too B. When expiresIn is omitted input expiresIn = (none) TTL = inherited from parent token expiresIn = now known! Before: there was no way to know when it would expire → This is the main pain point that has now been resolved
For tokens that inherit the parent TTL, you cannot "back-calculate from the input value," so previously there was no way to know the expiration time.The response's expiresIn fills that gap, which is the core of this update.

4Before vs. now comparison

ItemBeforeNow (2026-04 onward)
Knowing the expiration when expiresIn is specified Manual calculation Estimate it yourself from the input value Confirmed Get it from the response value
When expiresIn is omitted (parent TTL inherited) Not possible No way to know the expiration time Identified Returns seconds remaining
Aligns with REST delegate endpoint Expiration data existed only on REST Now aligned Equivalent data is now in GraphQL
Value format — Until expirationSeconds remaining(seconds remaining)
Target API version — 2026-04 and later

5Requirements

2026-04

GraphQL Admin API 2026-04 and later

This expiresIn field is available in GraphQL Admin API version 2026-04 and later. Apps calling older versions need to update their API version.

Setups using delegateAccessTokenCreate

Applies to apps that issue delegate tokens. The new field is included in the issuance response.No additional conditions such as eligible plans are mentioned in the article.

The article only covers four points: "2026-04 and later," "returns seconds remaining," "aligns with REST delegate endpoint," and "useful when unspecified." The exact type, nullability, and whether it applies retroactively to existing tokens are not mentioned. Verify actual values against the schema for the relevant version before adoption.

65 key points for engineers

sec

1. The value is "seconds remaining," not an "absolute timestamp"

expiresIn is the number of seconds until expiration. If you want to store it as an expiration time, derive your own timestamp withfetch time + expiresIn . It's timezone-independent, but you need to fix a reference point for the receive time.

parent child

2. Parent TTL inheritance when unspecified is the main use case

input expiresIn — when omitted, the child inherits the parent's TTL.Knowing the expiration in this case is the biggest gain from this update. If you always specify it explicitly, the benefit is limited; if you rely on inheritance, you can rework your refresh logic.

REST GQL

3. Equivalent data to the REST delegate endpoint

Aligns with the expiration data that was available from the REST Admin API delegate endpoint.Migrating from REST to GraphQL no longer drops expiration info — the incompatibility is resolved.

4. You can build proactive refresh

Instead of "noticing expiration only after hitting a 401,"check the seconds remaining and refresh in advancedesigns become possible, preventing intermittent failures caused by token expiration.

2026-04+

5. Retrieval requires a version update

expiresIn is version 2026-04 or lateris required for it to be returned. Apps pinned to older API versions must first upgrade their call version.Simply adding expiresIn to the query will not work on older versions— note this caveat. The article does not document retroactive application to existing tokens or specifications of other fields, so verify against the actual schema.

7Three use cases you can apply to your work

USE CASE 1

Proactively refresh delegate tokens to eliminate expiration-induced outages

Problem
Delegate tokens are passed to external services or backends in operation, but expiration timing is unpredictable, causing sporadic 401 failures the moment they expire.
Approach
Save the expiresIn from the issuance response and set up a job to reissue the token before the remaining seconds drop below a threshold.
Outcome
Shift from 'noticing expiration only after use' to 'refreshing proactively before the deadline.' Prevent intermittent payment and sync failures.
Technical note
Compute the expiration time from receipt time plusexpiresIn and cache it. Holding the remaining seconds directly becomes stale over time, so normalize to an absolute timestamp.
REST GQL
USE CASE 2

Migrate from the REST delegate endpoint to GraphQL with zero data loss

Problem
Existing logic written against the REST delegate endpoint needed to be consolidated onto the GraphQL Admin API, but the incompatibility — losing expiration data on migration — was a concern.
Approach
Upgrade to 2026-04 or later and use delegateAccessTokenCreate , retrieving expiration information equivalent to REST via the response's expiresIn .
Outcome
Consolidate on GraphQL without losing expiration information. Reduce REST dependency and align with the API's future direction.
Technical note
Cross-check the REST-side expiration representation against the field semantics (remaining seconds), and use regression tests to ensure the same expiration logic reproduces before and after migration.
USE CASE 3

Make the lifetime of parent-TTL-inherited tokens visible and integrate it into monitoring and alerts

Problem
Delegate tokens are issued in several places without an explicit expiration, inheriting the parent TTL, making it impossible to know which ones expire when — leaving operations a black box.
Approach
Log and emit metrics for the expiresIn returned at issuance, and visualize tokens with short remaining seconds on dashboards and alerts.
Outcome
The lifetime of inherited tokens — previously impossible to know — becomes visible, enabling pre-expiration refresh and inventory cycles.
Technical note
Inheritance behavior can't be reverse-engineered from inputs, so the response value is the only source of truth. Record the expiry timestamp on each issuance and have monitoring recompute the remaining time.

8One-line summary for proposals

"delegateAccessTokenCreate responses now include seconds remaining until expiry expiresIn (from 2026-04 onward).
For the first time, you can tell "when it expires" for tokens that inherit the parent TTL without specifying an explicit expiry, enabling
proactive refresh, monitoring, and migration from REST."