Skip to contents

API authorization state

APIAuthState.Rd

An APIAuthState object manages an authorization state for authentication with SpeedGoat APIs. When using a SpeedGoat API the user is identified by their email address and project ID. One email can be associated with multiple projects.

Authentication is organized by realms. A realm is a named group of APIs that share a single token authority. For example, the "counts" realm includes the counts API and any satellite APIs (e.g., sightability) that trust its tokens. Each realm stores its own token, refresh token, expiration, and auth type independently.

Authentication mechanisms include:

  • OIDC for shiny applications

  • API key for automated processes by end users

  • OAuth for interactive sessions

Methods

Public methods

Method new()

Create a new APIAuthState instance with default authentication endpoint

Usage

APIAuthState$new()

Returns

A new APIAuthState object

Method print()

Print authentication state information

Usage

APIAuthState$print()

Returns

Invisibly returns self (chainable)

Method init_realm()

Initialize a realm with default (unauthenticated) state.

Usage

APIAuthState$init_realm(name, base_url)

Arguments

name

Realm name

base_url

Base API URL for the realm (e.g., "https://counts.spdgt.com/api")

Returns

Invisible self (chainable)

Method get_realm()

Get realm state

Usage

APIAuthState$get_realm(name)

Arguments

name

Realm name

Returns

Named list with realm state

Method get_realm_for_api()

Get the realm name for a given API

Usage

APIAuthState$get_realm_for_api(api_name)

Arguments

api_name

API name

Returns

Realm name string, or NULL

Method set_realm_token()

Store credentials for a realm.

Usage

APIAuthState$set_realm_token(
  realm,
  token,
  refresh_token = NULL,
  expiration = NULL,
  auth_type = NULL
)

Arguments

realm

Realm name

token

Access token

refresh_token

Refresh token (optional)

expiration

Token expiration time (optional)

auth_type

Authentication type ("oauth", "oidc", or "api_key")

Returns

Invisible self (chainable)

Method get_realm_token()

Get token for a realm

Usage

APIAuthState$get_realm_token(realm)

Arguments

realm

Realm name

Returns

Token string or NULL

Method get_realm_auth_type()

Get auth type for a realm

Usage

APIAuthState$get_realm_auth_type(realm)

Arguments

realm

Realm name

Returns

Auth type string or NULL

Method get_realm_refresh_token()

Get refresh token for a realm

Usage

APIAuthState$get_realm_refresh_token(realm)

Arguments

realm

Realm name

Returns

Refresh token string or NULL

Method get_realm_expiration()

Get expiration for a realm

Usage

APIAuthState$get_realm_expiration(realm)

Arguments

realm

Realm name

Returns

Expiration POSIXct or NULL

Method is_realm_auth()

Check if a realm is authenticated

Usage

APIAuthState$is_realm_auth(realm)

Arguments

realm

Realm name

Returns

Logical

Method clear_realm_cred()

Clear credentials for a single realm.

Usage

APIAuthState$clear_realm_cred(realm)

Arguments

realm

Realm name

Returns

Invisible self (chainable)

Method forward_realm_token()

Forward a token to a specific realm.

Usage

APIAuthState$forward_realm_token(
  realm,
  token,
  expires_in = 3600,
  auth_type = "oidc"
)

Arguments

realm

Realm name

token

Token string

expires_in

Expiration time in seconds (default: 3600)

auth_type

Authentication type (default: "oidc")

Returns

Invisible self (chainable)

Method get_realm_url()

Derive auth URLs from a realm's base_url

Usage

APIAuthState$get_realm_url(realm, path)

Arguments

realm

Realm name

path

One of "me", "login", "refresh", "oidc", "logout"

Returns

URL string

Method add_api()

Register an API endpoint and assign it to a realm.

Usage

APIAuthState$add_api(name, url, package = NULL, realm = NULL)

Arguments

name

API name

url

API URL

package

Package registering the API. If NULL, will be detected from calling environment.

realm

Realm name. If NULL, creates a new realm named after the API. If provided, joins the existing realm.

Returns

Invisible self (chainable)

Method get_api_url()

Get the registered URL for an API by name.

Usage

APIAuthState$get_api_url(name)

Arguments

name

API name

Returns

API URL string

Method remove_api()

Remove an API registration.

Usage

APIAuthState$remove_api(name)

Arguments

name

API name

Returns

Invisible self (chainable)

Method get_user_agent()

Get the user agent string.

Usage

APIAuthState$get_user_agent()

Returns

User agent string

Method set_user_id()

Set user ID

Usage

APIAuthState$set_user_id(user_id)

Arguments

user_id

User ID

Returns

Invisible self

Method get_user_id()

Get user ID

Usage

APIAuthState$get_user_id()

Returns

User ID

Method set_email()

Set user email.

Usage

APIAuthState$set_email(email)

Arguments

email

Email address

Returns

Invisible self (chainable)

Method get_email()

Get user email

Usage

APIAuthState$get_email()

Returns

Email address

Method set_project_id()

Set project ID

Usage

APIAuthState$set_project_id(value)

Arguments

value

Project unique identifier

Method get_project_id()

Get project ID

Usage

APIAuthState$get_project_id()

Returns

Project unique identifier

Method set_project_abb()

Set project abbreviation

Usage

APIAuthState$set_project_abb(value)

Arguments

value

Project abbreviation string

Method get_project_abb()

Get project abbreviation

Usage

APIAuthState$get_project_abb()

Returns

Project abbreviation string or NULL

Method get_is_auth()

Get authentication status (any realm)

Usage

APIAuthState$get_is_auth()

Returns

Logical, TRUE if any realm is authenticated

Method clear_cred()

Clear all credentials (all realms and global identity).

Usage

APIAuthState$clear_cred()

Returns

Invisible self (chainable) user_id User's unique identifier email User's email address project_id Project unique identifier project_abb Project abbreviation Get user agent string User agent string

Method clone()

The objects of this class are cloneable with this method.

Usage

APIAuthState$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.