REST API Authentication

TableCrafter pulls table data from remote REST and JSON endpoints. This page documents exactly how the plugin authenticates those requests: Bearer-token auth for Airtable, query-string API keys for generic JSON APIs, and secure, encrypted storage for your Personal Access Token.

How authentication works in TableCrafter

Every table is rendered by the [tablecrafter] shortcode, which takes a single source attribute pointing at your data. The plugin inspects that URL and routes it to the right fetcher:

• Airtable sources (URLs starting with airtable://) are fetched through the Airtable REST API with a Authorization: Bearer header.
• Generic JSON/REST sources (any https:// endpoint returning JSON) are fetched as-is. Authentication is carried in the URL itself, typically as a query-string API key.
• Google Sheets and CSV sources are fetched as published/public documents and do not use API authentication.

Airtable: Bearer token authentication

Airtable is a first-class source. TableCrafter calls https://api.airtable.com/v0/{baseId}/{tableName} and sends your Airtable Personal Access Token (PAT) as a Bearer credential. The request sent to Airtable looks like this:

# Request TableCrafter makes on your behalf
GET https://api.airtable.com/v0/appSampleBaseId/Employees
Authorization: Bearer patXXXXXXXXXXXXXX
Content-Type: application/json

You reference an Airtable base with the airtable:// URL scheme. The format is:

airtable://{baseId}/{tableName}?token={pat}&view={viewId}

Airtable URL parameters

Recommended: store the token once, omit it from the URL

Putting a token in a shortcode means it can appear in post content and revisions. The safer pattern is to save your PAT once in the admin, then reference the base without a token parameter:

// Token stored in settings, never exposed in page content
[tablecrafter source="airtable://appSampleBaseId/Employees"]

// With an optional view and selected columns
[tablecrafter source="airtable://appSampleBaseId/Employees?view=viwGridView" include="Name,Role,Email" search="true"]

When no token is present in the URL, TableCrafter loads the value of the tablecrafter_airtable_token option, decrypts it, and uses it as the Bearer credential.

Saving your Airtable token

1. In wp-admin, open TableCrafter (the top-level menu, slug tablecrafter-wp-data-tables).
2. In the shortcode builder, click the Airtable connect button.
3. Paste your Personal Access Token and save. The value is encrypted before it is written to the database.

Saving is handled by a nonce-protected AJAX action (tc_save_airtable_token) that requires the manage_options capability, so only administrators can store credentials. The raw token is never persisted in clear text; it is encrypted with the plugin's security layer and only decrypted in memory at request time.

Generic REST / JSON: query-string authentication

For any other REST endpoint, set source to the full HTTPS URL of the JSON resource. TableCrafter fetches that exact URL, so APIs that authenticate via a query-string key work out of the box:

// API key passed as a query parameter
[tablecrafter source="https://api.example.com/v1/orders?api_key=YOUR_KEY" root="data"]

// Token-style query parameter
[tablecrafter source="https://api.example.com/report.json?access_token=YOUR_TOKEN"]

The endpoint must return a JSON array of objects (or an object you can drill into with the root attribute, e.g. root="data.items"). The response is parsed and cached for one hour.

What about custom request headers?

To be precise about the plugin's surface: the [tablecrafter] shortcode does not expose attributes for arbitrary request headers, a custom Authorization header, or an X-API-Key header on generic REST sources. There is no headers, auth, or api_key shortcode attribute.

Header-based Bearer authentication is implemented and supported, but it is wired specifically to the Airtable integration. If your API only accepts an Authorization or X-API-Key header (and rejects query-string keys), the supported approaches are:

• Use the Airtable source if your data lives in Airtable.
• Place a small proxy endpoint on your own server that adds the required header, then point source at the proxy.
• Switch the upstream API to a query-string credential where the provider supports it.

Transport security and SSRF protection

Every remote fetch goes through TableCrafter's hardened HTTP layer, which applies the following safeguards regardless of authentication method:

Authentication error reference

When an Airtable request fails, TableCrafter surfaces a specific error so you can pinpoint the credential problem:

Generic JSON sources that fail authentication typically return a non-200 status, surfaced as an HTTP error, or an unexpected body, surfaced as a JSON parse error. Confirm your key is valid by opening the full source URL directly in a browser.

Caching and credentials

Successful responses are cached: one hour for generic REST/JSON sources and five minutes for Airtable (to respect its rate limits). The cache key is derived from the source URL and display options, so the URL, including any query-string key, is part of what determines a cache hit. Rotating a key or changing the token does not invalidate an old cache entry until it expires, so allow up to the cache window for a credential change to take effect, or change the source URL to force a fresh fetch.

Next, see airtable-source.html for the full Airtable setup walkthrough, and json-rest-sources.html for shaping nested responses with the root and include attributes.