REST API

What It Is

Jetstack exposes a versioned REST API for authentication, collection access, command execution, filtering, ordering, paging, field selection, and file-aware operations.

Why It Matters

The REST API is the main external integration surface for many conventional system-to-system scenarios.

Main Capabilities

Authentication

The API supports:

• creating API keys by user credentials
• validating an existing key
• revoking a key

This makes API access an explicitly permissioned tenant capability rather than an always-on anonymous interface.

Collection Access

The API can:

• target a collection by type
• retrieve specific items
• retrieve by alternative property
• use field show and hide controls
• use paging and ordering
• apply filters

Command Processing

The API also supports command-style paths, which means the surface is not limited to static collection retrieval.

Account Verification Lifecycle

When an integration creates user accounts through the API, those accounts can be required to complete a verification challenge before the user is allowed to sign in. The challenge is configured by the integration that initiates the registration and can include any combination of:

• a one-time link sent by e-mail
• a numeric code sent by e-mail
• a numeric code sent by SMS

Three actions cover the lifecycle:

• register — creates the user, issues the challenge if requested, and returns its identifier so the integration can correlate later steps
• challenge — validates the code or link the user supplied; once every method on the challenge is satisfied, the account is activated
• retry challenge — re-sends the notification for an outstanding challenge with a freshly generated secret

The retry capability matters when the original message did not arrive, when a link expired before the user clicked it, or when the user returns later — possibly from a different browser or device — and the integration no longer holds the original challenge identifier. Each retry rotates the underlying secret, so any previously delivered link or code stops working as soon as the retry is processed — leaked or stale codes cannot be reused alongside the new one. Server-side cooldown and a lifetime retry cap bound the cost of abuse on this surface.

File Handling

The runtime accounts for file uploads and file-oriented field handling where needed.

Response Caching

GET and SEARCH requests against the generic collection API are served from a transparent server-side cache. The cache stores fully-projected JSON payloads — the same bytes the API would otherwise produce — and is consulted before any database work happens.

Three request shapes are cached:

• list responses (with filters, paging, ordering)
• get-one-by-id responses
• get-one-by-property responses

The cache is per user: every entry's lookup key includes the authenticated user's identity and effective permission scope, so two users never see each other's filtered view.

Two invalidation strategies cooperate:

• Single-resource entries are flushed automatically when the resource is created, updated, or deleted through the platform. The next request after a mutation always sees fresh data.
• List entries rely on a short time-to-live (5 minutes by default) plus a best-effort flush on writes against the same type. Filter-aware invalidation across an unbounded matrix of filter combinations is intentionally not attempted — the TTL bounds staleness instead.

Every cached response also carries an ETag. Clients that send If-None-Match on a subsequent request receive 304 Not Modified and an empty body, saving bandwidth. Setting an ETag does not require the client to support conditional requests — it is opportunistic.

Caching is bypassed for:

• mutating methods (POST, PUT, PATCH, DELETE) — they are never cached
• requests carrying Cache-Control: no-cache or ?_noCache=1
• single-resource fetches against a type that has read-access logging enabled, so the audit log fires on every read

Operators can monitor and purge the cache from the Application Management screen.

Governance

REST access depends on system permissions such as:

• useApi
• user registration support
• user password-reset support
• generating others' API keys

This means the REST API must be part of the tenant's security design, not treated as a side channel.

Reference

Use REST API Reference when you need concrete routes, request parameters, response shapes, and module-specific endpoint details.

Credential Model And Application Users

REST API access is user-bound. An API key authenticates as the User that owns the key, and the platform then evaluates permissions through that user identity.

This has several important consequences:

• the user must be allowed to use the API
• the user’s roles determine what the API may do
• the user validity window also affects whether the key remains usable
• created and updated records remain attributable to that acting user identity

Because of that, the recommended pattern is to create a dedicated application user for each important integration.

Why this pattern is a good practice

• permissions stay minimal and reviewable
• integrations are not tied to a real employee account
• audit history remains understandable
• revocation is simpler and safer

Recommended setup

1. Create a dedicated User such as Application CRM Connector.
2. Assign only the roles needed by the integration.
3. Place the user into a dedicated Group such as Application access.
4. Generate the API key for that user.
5. Keep the key lifetime and user validity window aligned with the integration lifecycle.

Important note about scope

In the normal administrative API-key flow, the key primarily inherits the owning user’s identity and permissions. In other words, the usual security boundary is the user account and its roles, not a large independent per-key permission model.

Filtering And Field Shape

API consumers need to understand:

• filter structure
• ordering conventions
• field visibility controls
• multiple-value return shape

Some of that behavior is further influenced by application settings.

Timezones

All datetime columns are stored in UTC on the server. The user-facing wall-clock you see in the application UI is computed at render time from the per-tenant default timezone and the optional per-user timezone field.

Writes

When you send a datetime value (in a POST/PUT/PATCH body or as a query parameter), the safest and most explicit shape is ISO 8601 with a timezone offset:

2026-05-22T09:00:00+02:00    (Prague summer wall-clock)
2026-05-22T07:00:00Z          (same instant, UTC)
2026-05-22T03:00:00-04:00     (same instant, New York summer)

All three above are stored identically: 2026-05-22 07:00:00 UTC.

If you send a naive datetime string without any zone information (2026-05-22 09:00:00 or 2026-05-22T09:00:00), the platform interprets it in the user's display timezone — same convention as the application's own form inputs. This is the right behavior for integrations that pass through user-entered values, but if your integration computes timestamps server-side, prefer ISO 8601 with explicit offset to avoid ambiguity.

Filters (reads)

The same rules apply to filter values. A filter expressed as created_on >= 2026-05-22T09:00:00+02:00 is internally compared against UTC 07:00:00 regardless of any user's display tz. A naive 2026-05-22 09:00:00 is interpreted in the calling user's display tz first, then normalized to UTC for the comparison.

Responses

Datetime values in API responses are emitted as ISO 8601 with an explicit offset in the acting user's display timezone (e.g. 2026-05-22T09:00:00+02:00 for a Prague-tenant user — same wall-clock the application UI would show, with the offset making the absolute instant unambiguous).

The display timezone is resolved per-request from: the API key user's timezone field if set → tenant defaultTimeZone → UTC. Two consequences worth knowing:

• The same record can serialize with different offsets depending on the API key used to fetch it (different users may have different timezone settings). The instant is identical; the wall-clock view differs.
• Calendar fields (pDate, pMonth) emit YYYY-MM-DD (or YYYY-MM) — no time, no offset. They are not affected by the user's display tz.

Calendar dates (date-only fields)

Fields backed by pDate or pMonth properties (birthdays, "valid from", month-of-record, etc.) are calendar values without time-of-day or timezone semantics. They are stored as date-only and emitted as YYYY-MM-DD (or YYYY-MM for month). Sending an ISO 8601 datetime with a time component is accepted — the time and offset are discarded; only the date portion is kept. These fields never shift across timezones.

Summary

Best Practices

• treat API keys as secrets
• do not expose API keys in frontend of your integrated apps (use lightweight server proxy to communicate with the backend)
• use dedicated application users or clearly owned service identities
• document which types and fields are intended for API consumption
• keep application-level multiple-value return settings stable after integrations are live
• put integration users into a dedicated operational group such as Application access
• use role design and user validity windows as part of the integration security model
• when integrating high-traffic clients, prefer fewer parameter shapes — every distinct filter or field selection produces its own cache entry
• support If-None-Match in clients that handle a lot of polling traffic; conditional 304 responses reduce bandwidth without changing the caching guarantees
• send datetime values as ISO 8601 with explicit timezone offset (e.g. 2026-05-22T09:00:00+02:00); avoid naive strings whose meaning depends on the receiving user's display tz

Related Chapters

• REST API Reference
• Application Management
• Application Settings
• Secret Store
• Roles And Permissions
• Users