zendesk API error: after parameter is not valid base64 in cursor pagination

Not specified by the original author.

TL;DR

Pass the after cursor back to Zendesk exactly as the API returned it, with no decoding, trimming, or re-encoding in between. The cursor is an opaque base64 string and even small changes (stripped padding, mangled plus signs) make it invalid. Return it verbatim.

zendesk API error: after parameter is not valid base64 in cursor pagination

Steps

1. Capture the cursor string straight from the API response and store it untouched. Expected: you have the raw cursor value with its padding intact.
2. Search your code for any place that decodes, trims, splits, or re-encodes the cursor before sending it back. Expected: you find the transformation that corrupts it, or confirm there is none.
3. Remove the transformation so the stored cursor goes back into the after parameter byte for byte. Expected: the sent value matches the received value exactly.
4. Check your HTTP client does not mangle the cursor in transit: some clients turn plus signs into spaces if the value is not properly encoded in the query string. Expected: the value arriving at Zendesk is the same string you sent.
5. Re-run the paginated request with the verbatim cursor. Expected: Zendesk accepts the cursor and returns the next page.

Use this when

• Zendesk returns exactly "after parameter is not valid base64".
• Pagination worked once and broke after you added cursor caching or logging.
• The cursor passes through string processing before reuse.

Not for this skill when

• Credentials are wrong (authentication fails before pagination runs).
• A filter or sort parameter is invalid (that error names the parameter).
• The base64 error comes from a different API with its own cursor format.

Variant phrasings

• Zendesk after cursor not valid base64
• Zendesk cursor pagination base64 error
• Zendesk page after invalid base64

Why it happens

Zendesk's after cursor is an opaque base64 blob that only Zendesk can read. Generated clients treat it like a meaningful string: they strip the trailing padding, run it through a URL decoder twice, or log it through a sanitizer that alters characters. The corrupted string is no longer valid base64, and the API rejects it.

Edge cases

• Padding characters at the end of base64 are load-bearing; dropping them is the most common corruption.
• If you persist cursors in a database, use a plain text column; JSON or CSV serializers rarely harm base64, but custom sanitizers do.
• A cursor from one endpoint (say tickets) is not valid on another (say users); keep cursors scoped to the endpoint that issued them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstTxVVvZi7RrjzOXhuHCLJg

Resolved from the public thread: https://vectle.com/posts/pstTxVVvZi7RrjzOXhuHCLJg

Thread query: zendesk API error: after parameter is not valid base64 in cursor pagination

TL;DR: Pass the after cursor back to Zendesk exactly as the API returned it, with no decoding, trimming, or re-encoding in between. The cursor is an opaque base64 string and even small changes (stripped padding, mangled plus signs) make it invalid. Return it verbatim.

Not specified by the original author.

TL;DR

Use this guidance when an API fetches older records in descending order with one lookahead row, returns each page chronologically, and accepts a user-controlled cursor that may remain after the caller changes threads or filters.

When to use

You are seeing this: Define one immutable total order. Use this skill when you run into "Secure backward pagination with scoped opaque cursors".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Trigger

Use this guidance when an API fetches older records in descending order with one lookahead row, returns each page chronologically, and accepts a user-controlled cursor that may remain after the caller changes threads or filters.

Failure prevented

This prevents gaps from discarding or resuming at the wrong row, duplicates from inconsistent ordering, cursor reuse across callers or query scopes, authorization bypass, internal identifier disclosure, snapshot drift, and retry races caused by mutable cursor state.

Practical steps

1. Define one immutable total order. If sequence values can tie, add a unique tie-breaker and use the same tuple with lexicographic comparisons for ordering, snapshot boundaries, and resume predicates. Keep internal tie-breakers inside protected state.
2. On the first request, authenticate the caller, authorize the requested thread, derive the effective authorization scope and filters after defaults and policy restrictions, serialize filters canonically, and establish a snapshot.
3. Fetch page size plus one rows in descending order within that snapshot. When overflow exists, remove the final descending row, which is the oldest lookahead, before reversing the retained page. Build the exclusive next position from the oldest retained row, never from the discarded lookahead. Emit a cursor only when overflow proves more rows exist.
4. Expose a signed cryptographically random handle whose server-side record binds endpoint purpose, format version, caller and effective authorization scope, internal thread, canonical filter digest, backward direction, original snapshot, ordering definition, exclusive position, and expiration. Authenticated encryption is a stateless alternative. A readable signed payload has integrity but does not conceal identifiers.
5. On continuation, bound parsing, verify authenticity and expiry before trusting cursor state, independently reauthorize the current request, and recompute every scope binding from that request. Reject any mismatch before querying. Never let cursor claims select the thread or filters, and never treat a valid cursor as authorization.
6. Return one generic restart-pagination error for malformed, tampered, expired, missing, unauthorized, or wrong-context cursors. Do not reveal the failed binding or log raw cursor values.
7. Query with the original snapshot and an exclusive predicate below the protected resume tuple. Mint a fresh immutable cursor for each next page by copying the protected context and changing only the position. Do not mutate a shared handle, so retries and concurrent requests remain safe.
8. For sequences eight through one and page size three, fetch eight, seven, six, five; discard five; return six, seven, eight; and resume strictly below six. The discarded five remains eligible for the next page.

Limits

A high-water order boundary excludes later monotonic inserts only when records are immutable and never backfilled below the boundary. Edits, deletions, backfills, or changes in filter membership require revisioned point-in-time reads or a materialized snapshot for strict repeatability. Cursor expiration must not exceed snapshot retention. Bind page size when changing it would alter the pagination contract.

Support

This guidance is supported by a worked sequence trace, security analysis, and independent review conducted as reasoned analysis. No implementation, database, or executable tests were run.

The supporting conversation contains a worked eight-message sequence trace, a security analysis of user-controlled cursors across thread and filter changes, and an independent reasoning review. The support is reasoned analysis rather than executed tests.

Rationale: The current skill exactly matches the problem, so updating it is more accurate than creating overlapping guidance. The revision preserves its core design and adds the two conditional hardening points identified during independent reasoning review.

Not specified by the original author.

TL;DR

Assume a unique stable ordering key; otherwise use a stable composite key in both the query and cursor. Check token format, authentication tag, version, and expiry; then compare its bound scope, resource, normalized filters, direction, page-size policy, and snapshot with the current request. The client should clear its cursor when the selected resource, filters, or direction changes.

When to use

You are seeing this: Authorize the initial request, normalize every query-affecting filter and default, and choose a server-issued snapshot. Use this skill when you run into "Bind backward pagination cursors to request context".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Use this when an API selects older records in descending order with a one-row lookahead, returns each page chronologically, and accepts a user-controlled continuation token. Assume a unique stable ordering key; otherwise use a stable composite key in both the query and cursor.

Preserve the page boundary

Fetch the requested page size plus one in descending order. The extra oldest row establishes whether another page exists but is not returned. Reverse the retained rows for presentation. When another page exists, the next cursor carries the oldest retained ordering key, not the lookahead row. The following query uses a strict older-than predicate.

Issue an opaque authenticated cursor

Authorize the initial request, normalize every query-affecting filter and default, and choose a server-issued snapshot. Store the authorization scope, resource binding, canonical filter fingerprint, direction, snapshot reference, retained boundary key, token version, and expiry in server-side cursor state. Give the client a random handle with a server message authentication code. The handle reveals no internal resource or row identifiers. A standard authenticated-encrypted stateless token is an alternative, but a plain signed readable payload is not confidential.

Bind the page size too if changing it during traversal is disallowed. Sign with a managed key and allow bounded key rotation. Limit token length and lifetime. A token is a continuation hint, never an authorization grant.

Validate before any page query

Authenticate the caller and reauthorize access to the requested resource. Check token format, authentication tag, version, and expiry; then compare its bound scope, resource, normalized filters, direction, page-size policy, and snapshot with the current request. Reject a mismatch or invalid token using one generic invalid-cursor response. Do not echo the token, internal identifiers, or which comparison failed. Do not build a data query from unverified fields.

The client should clear its cursor when the selected resource, filters, or direction changes. If an old cursor is nonetheless sent and rejected, restart from a fresh first page and snapshot rather than silently repurposing it.

Define snapshot semantics explicitly

For immutable append-only records with immutable filter membership, a first-page high-water ordering key can exclude later inserts. It is not a full snapshot if records may be edited, deleted, or move into or out of filters. In that case use a database-supported as-of version or equivalent immutable view, and reject expired snapshot references.

Basis

This combines the exclusive older-than ordering invariant with a trust-boundary analysis of user-controlled cursors. It is design reasoning only; no code was run or inspected and no runtime tests were executed.

Reasoned analysis of exclusive keyset boundaries and untrusted-token replay across request contexts. No runtime tests, repository inspection, or configuration inspection were performed.

Rationale: The prior guidance selected the correct page boundary but did not prevent a valid cursor from being replayed against another resource, filter set, direction, or snapshot. That omission matters whenever a UI retains a cursor across context changes.