Authentication & Credential Vending

Gnok Catalog authenticates every request with an OAuth2 bearer token and authorizes it against a set of scopes. For data access, it then vends short-lived, location-scoped cloud credentials so clients never hold long-lived storage keys.

Getting a token

Gnok Catalog exposes an OAuth2 token endpoint at POST /v1/oauth/tokens (form-encoded, per OAuth2). The most common flow for an engine or service is the client-credentials grant:

curl -s -X POST https://catalog.example.com/v1/oauth/tokens \
  -d grant_type=client_credentials \
  -d client_id=<client-id> \
  -d client_secret=<client-secret> \
  -d scope='catalog:read namespace:read table:read table:data'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "catalog:read namespace:read table:read table:data"
}

Supported grant_type values:

Grant type	Use
client_credentials	Service/engine authentication with a client id + secret.
refresh_token	Exchange a refresh token for a fresh access token.
urn:ietf:params:oauth:grant-type:token-exchange	RFC 8693 token exchange (e.g. a trusted service exchanging a session for an access token).

Most Iceberg clients implement the OAuth2 handshake for you — you supply a credential of the form client-id:client-secret (Spark, Trino, PyIceberg) and the client calls /v1/oauth/tokens, caches the access_token, and refreshes it before expires_in elapses. You only call the endpoint directly when scripting or debugging.

Presenting the token

Send the access token on every request:

Authorization: Bearer <access_token>

Scopes

Authorization is scope-based. Tokens carry one or more of the following scopes, and the catalog enforces them per HTTP method:

Scope	Grants
catalog:read	List and load catalog-level metadata.
catalog:write	Create and drop catalogs.
namespace:read	List and load namespaces.
namespace:write	Create and drop namespaces, update properties.
table:read	List and load tables and views.
table:write	Create, commit, rename, register, and drop tables/views.
table:data	Receive vended storage credentials for table data.

A read-only analytics client typically requests catalog:read namespace:read table:read table:data. A client that also writes tables additionally needs table:write (and namespace:write to create namespaces).

Credential vending

Gnok Catalog can return scoped, short-lived storage credentials alongside table metadata, so an engine reads and writes data files directly against object storage without ever being configured with long-lived cloud keys.

Requesting vended credentials

Send the standard Iceberg access-delegation header on table-load requests:

X-Iceberg-Access-Delegation: vended-credentials

Most engines set this for you when a vended-credentials option is enabled (see Connecting external engines). When present, the loadTable response includes a storage-credentials array; each entry has a prefix (a storage location) and a config map of provider-specific properties. A client selects the credential whose prefix is the longest match for the location it is accessing.

Credential properties by cloud

The config map uses the standard Iceberg FileIO property names:

AWS S3

Property	Meaning
s3.access-key-id	Temporary access key.
s3.secret-access-key	Temporary secret key.
s3.session-token	STS session token.
s3.region	Bucket region.
s3.session-token-expires-at-ms	Expiry, epoch milliseconds.

Google Cloud Storage

Property	Meaning
gcs.oauth2.token	OAuth2 access token.
gcs.oauth2.token-type	Token type (usually Bearer).
gcs.oauth2.token-expires-at-ms	Expiry, epoch milliseconds.
gcs.project-id	GCP project id.

Azure ADLS

Property	Meaning
adls.account-name	Storage account name.
adls.sas-token	SAS token.
adls.sas-token-expires-at-ms	Expiry, epoch milliseconds.

Vended credentials are time-limited; clients re-request them (by reloading the table with the delegation header) as they approach expiry.

Batch vending and remote signing

• Batch vending — POST /v1/{catalog}/tables/credentials/batch returns credentials for many tables in a single request, which engines use to plan multi-table queries efficiently.
• Remote signing — instead of receiving credentials, a client can ask the catalog to sign individual object-storage requests via POST /v1/{catalog}/namespaces/{namespace}/tables/{table}/sign (request X-Iceberg-Access-Delegation: remote-signing). The response returns presigned URLs with an expires-at-ms per URL.

See the REST API reference for the full set of credential and signing endpoints.