OAuth Module

Built-in OAuth for API authentication

Handle OAuth automatically in your pipeline.

No token storage. No refresh logic. No glue code.

The oauth module manages tokens for you — including automatic refresh. It is a predeclared global — no import needed.

Why This Exists

Most API ingestion requires manual token handling:

• Store tokens
• Track expiration
• Refresh before expiry
• Retry failed requests

With OndatraSQL, this is built in. You request a token. The runtime keeps it valid.

Mental Model

• oauth.token() creates a managed token
• token.access_token always returns a valid token
• Refresh happens automatically when needed

You don’t manage authentication — you use it.

Automatic Token Refresh

Tokens are refreshed automatically before they expire.

• No manual refresh logic
• No expiry tracking
• No retry handling required

Accessing token.access_token always gives you a valid token — even for long-running scripts.

oauth.token

Returns a managed token that stays valid automatically.

Client Credentials

token = oauth.token(
    token_url="https://auth.example.com/oauth/token",
    client_id=env.get("CLIENT_ID"),
    client_secret=env.get("CLIENT_SECRET"),
    scope="read write",
)

resp = http.get(url, headers={"Authorization": "Bearer " + token.access_token})

Google Service Account

Use service accounts for Google APIs (BigQuery, Ad Manager, etc.).

token = oauth.token(
    google_service_account=env.get("GOOGLE_KEY_JSON"),
    scope="https://www.googleapis.com/auth/bigquery.readonly",
)

# Or from file:
token = oauth.token(
    google_key_file="service-account.json",
    scope="https://www.googleapis.com/auth/admanager",
)

One of google_service_account or google_key_file is required for the Google flow.

Works with the HTTP Module

Use the token directly in requests:

resp = http.get(url, headers={
    "Authorization": "Bearer " + token.access_token,
})

Authentication, retries, and data ingestion work together seamlessly.

Full Example

# @kind: append

token = oauth.token(
    token_url="https://auth.example.com/oauth/token",
    client_id=env.get("CLIENT_ID"),
    client_secret=env.get("CLIENT_SECRET"),
    scope="read:users",
)

page = 1
while True:
    resp = http.get(
        "https://api.example.com/users",
        headers={"Authorization": "Bearer " + token.access_token},
        params={"page": str(page)},
    )
    users = resp.json["data"]
    if not users:
        break
    for user in users:
        save.row({"id": user["id"], "name": user["name"]})
    page += 1

oauth.basic_auth

HTTP Basic Authentication header:

header = oauth.basic_auth(env.get("USERNAME"), env.get("PASSWORD"))
# "Basic base64encoded..."

Compared to Traditional OAuth

Traditional approach:

• Use OAuth libraries
• Store tokens in files or databases
• Implement refresh logic
• Handle expiration errors

OndatraSQL:

• Request a token once
• Use token.access_token
• Refresh handled automatically