#oauth API reference

A generic OAuth2 client: the get-a-token half of OAuth2 (the use-a-token half is sasl XOAUTH2). Acquires and refreshes access tokens against any OAuth2 token endpoint, over http + json. Ships the flows that need no extra dependencies: Client Credentials (a service authenticating as itself), Refresh Token (trade a refresh token for a fresh access token), and the Device Authorization Grant (the CLI-friendly flow: show the user a URL + code, poll the token endpoint until they approve). Authorization Code + PKCE and the service-account JWT assertion need a local redirect server and crypto-grade signing, so they land later. Provider presets for Google and Microsoft 365 fill in the endpoints. Because it builds on http (which uses net), this module needs the default jennifer binary. A token-endpoint error surfaces as a catchable Error (kind "oauth").

Import with import "oauth.j" as oauth;. See the oauth guide for prose and examples.

#Functions

#oauth.clientCredentials(config as Config)

Acquire a token for the client itself (no user).

Parameters

• config {Config} - the client settings

Returns {Token} - the issued access token

Throws

• {Error} - kind "oauth" on a token-endpoint error

#oauth.deviceStart(config as Config)

Begin the device flow: return the code + URL to show the user.

Parameters

• config {Config} - the client settings

Returns {DeviceAuth} - the device-authorization handle

Throws

• {Error} - kind "oauth" on a device-endpoint error

#oauth.deviceWait(config as Config, deviceAuth as DeviceAuth)

Poll the token endpoint until the user approves (or a terminal error), returning the token. Sleeps interval seconds between polls, backing off on slow_down.

Parameters

• config {Config} - the client settings
• deviceAuth {DeviceAuth} - the handle from deviceStart

Returns {Token} - the issued access token

Throws

• {Error} - kind "oauth" if device authorization fails

#oauth.google(clientId as string, clientSecret as string, scope as string)

Return a Config for Google's OAuth2 endpoints.

Parameters

• clientId {string} - the OAuth2 client identifier
• clientSecret {string} - the OAuth2 client secret
• scope {string} - the space-separated requested scopes

Returns {Config} - a Config wired to Google's endpoints

#oauth.isExpired(token as Token)

Report whether a token has expired (30s skew buffer).

Parameters

• token {Token} - the token to check

Returns {bool} - true if the token is at or past its expiry

#oauth.load(path as string)

Read a token previously written by save.

Parameters

• path {string} - the file path to read

Returns {Token} - the loaded token

#oauth.microsoft(tenant as string, clientId as string, clientSecret as string, scope as string)

Return a Config for a Microsoft 365 / Entra tenant's endpoints.

Parameters

• tenant {string} - the tenant identifier (or "common")
• clientId {string} - the OAuth2 client identifier
• clientSecret {string} - the OAuth2 client secret
• scope {string} - the space-separated requested scopes

Returns {Config} - a Config wired to the tenant's endpoints

#oauth.refresh(config as Config, refreshToken as string)

Trade a refresh token for a new access token, preserving the refresh token when the server omits it from the reply.

Parameters

• config {Config} - the client settings
• refreshToken {string} - the refresh token to redeem

Returns {Token} - the new access token

Throws

• {Error} - kind "oauth" on a token-endpoint error

#oauth.save(path as string, token as Token)

Write a token to a file as JSON (its own field shape, round-trips with load; absolute expiresAt is preserved). The file is tightened to owner-only (0600) after writing, since an OAuth token is a bearer credential - the same file-permission model gh / aws use for their token stores, so it is not left world-readable at the write verbs' default 0644.

Parameters

• path {string} - the file path to write
• token {Token} - the token to persist

#Structs

#oauth.Config

The OAuth2 client settings for one provider / application.

#oauth.DeviceAuth

A device-authorization handle: show the user verificationUri + userCode, then deviceWait polls with deviceCode every interval seconds.

#oauth.Token

An issued token. expiresAt is a Unix timestamp (seconds; 0 = no known expiry).