Use one login for several APIs

One login, different API tokens

A calendar service and a contacts service can require different access tokens, even when the same person uses both. A token target names an API and the permissions the app needs there. The app chooses the target when requesting a token, without requiring a separate login flow for each API.

Targets rely on provider support for RFC 8707 resource indicators or Microsoft’s API-specific scopes. The provider’s registration and consent determine which APIs the login can access.

For independent logins or different accounts, use Multiple authorizations. For initial login setup, start with Usage.

Configure two APIs

This example uses a provider with RFC 8707 support. A resource identifier names an API to the login provider; a scope names a permission. resource_bases lists the actual HTTP addresses the app may call, which can differ from the resource identifiers.

Replace all example settings with your provider’s registered values. Microsoft uses the alternative setup shown below.

# Provider supports RFC 8707 resource indicators.
provider <- oauth_provider(
  "workplace", "https://login.example/authorize", "https://login.example/token",
  token_target_mode = "rfc8707",
  token_auth_style = "body",
  userinfo_required = FALSE
)
client <- oauth_client(
  provider,
  client_id = Sys.getenv("OAUTH_CLIENT_ID"),
  client_secret = Sys.getenv("OAUTH_CLIENT_SECRET"),
  redirect_uri = "https://app.example/callback",
  token_targets = list(
    calendar = oauth_token_target(
      resource = "https://calendar.example/",
      scopes = c("calendar.read", "calendar.write"),
      required_scopes = "calendar.read",
      resource_ids = "calendar_api"
    ),
    contacts = oauth_token_target(
      resource = "https://contacts.example/",
      scopes = "contacts.read",
      resource_ids = "contacts_api"
    )
  ),
  token_target_default = "calendar",
  resource_bases = c(
    calendar_api = "https://calendar.example/v1",
    contacts_api = "https://contacts.example/v1"
  )
)

token_target_default chooses the API when a call omits target. oauth_token_target() checks each declaration’s fields; plain named lists with the same fields remain supported. The client checks provider-specific rules and how declarations relate to one another. Omitting client scopes uses the union of API permissions declared by the targets. If you supply scopes, include every target’s permissions: that explicit list remains the limit and is never expanded automatically. Identity and refresh consent, such as profile or offline_access, still need an explicit request; OIDC continues to add openid when needed. resource_ids connects each target to its named API address in resource_bases. You can omit those addresses when only exporting tokens to another package.

Choose a token when making a call

Get a connection from the module and pass target to select the API. Replace existing_contacts_sdk() with your contacts package’s client constructor:

server <- function(input, output, session) {
  auth <- oauth_module_server(
    "auth", client,
    reauth_after_seconds = 60 * 60 # One-hour maximum login age
  )
  # Alternatively: auth <- oauth_connections_server("auth", manager)
  # and select auth$connection(connection_id), or auth$connection() when unique.

  contacts <- shiny::reactive({
    connection <- shiny::req(auth$connection())
    token <- connection$access_token("contacts.read", target = "contacts")
    existing_contacts_sdk(access_token = token)$list_contacts()
  })

  output$can_edit_calendar <- shiny::renderText({
    connection <- shiny::req(auth$connection())
    connection$has_scopes("calendar.write", target = "calendar")
  })

  shiny::observeEvent(input$save_event, {
    connection <- shiny::req(auth$connection())
    connection$request(
      "calendar_api", "events", method = "POST",
      required_scopes = "calendar.write", target = "calendar", refresh = TRUE,
      configure = function(req) httr2::req_body_json(req, list(title = input$title))
    )
  })
}

$access_token() obtains or refreshes the chosen token when needed. $has_scopes() checks permissions already recorded; it can return FALSE before that target’s first token acquisition. $targets() lists target status without exposing credentials.

Use $is_usable(target = "contacts") to check whether that API’s current token is usable, or $summary(target = "contacts") to inspect its status and expiry. These reads never acquire or refresh a token; an unacquired target has status "not_acquired" and is not usable.

The example limits login to one hour with reauth_after_seconds. Without a limit, local authentication can outlast every API token; indefinite_session = TRUE disables that limit.

Refresh and sign in again

For RFC 8707 providers, reduce one target’s permissions with, for example, connection$refresh(scopes = "calendar.read", target = "calendar"). The selected scopes must include the target’s required permissions.

auth$reauthorize() starts a replacement login with the reduced permissions. For managed connections, pass the connection ID. Once replacement starts, cancelling does not restore the old login. An ordinary new login asks for the client’s original permissions again.

Microsoft example

Microsoft uses API-qualified scope names to select the token’s intended API. Use the exact names from your registration. This example exports tokens to another package:

provider <- oauth_provider_microsoft(
  tenant = Sys.getenv("MICROSOFT_TENANT_ID"),
  userinfo_required = FALSE
)
client <- oauth_client(
  provider, Sys.getenv("OAUTH_CLIENT_ID"), Sys.getenv("OAUTH_CLIENT_SECRET"),
  redirect_uri = "https://app.example/callback",
  scopes = c(
    "openid", "offline_access",
    "https://graph.microsoft.com/Calendars.Read",
    "api://your-contacts-api/Contacts.Read"
  ),
  token_targets = list(
    calendar = oauth_token_target(
      resource = "https://graph.microsoft.com",
      scopes = "https://graph.microsoft.com/Calendars.Read"
    ),
    contacts = oauth_token_target(
      resource = "api://your-contacts-api",
      scopes = "api://your-contacts-api/Contacts.Read"
    )
  ),
  token_target_default = "calendar"
)

userinfo_required = FALSE skips the Graph profile request, which would be inappropriate for a token intended for another API. Add resource_bases and each target’s resource_ids if you also want to call $request().

Advanced: provider support and declaration limits

Targets share a login and refresh credential but keep separate API tokens and permission limits. Enable token_target_mode = "rfc8707" or "microsoft" only after confirming provider support; discovery does not infer it.

Targets require userinfo_required = FALSE and cannot be combined with SMART configuration or the client’s resource argument. Use the module’s connection() method, since the older oauth_connection() wrapper does not support targets. Up to 16 targets are supported.

Advanced: Microsoft permissions and consent

Microsoft can return previously consented permissions beyond those needed for the current operation. Connection methods enforce the app’s local limits, but an exported token carries the provider’s full grant.

Explicit API narrowing with $refresh(scopes = ...) fails with unsupported_scope_narrowing and leaves the login usable. Change provider consent or use a separate registration if the token itself needs fewer permissions.

Advanced: concurrent refreshes and failures

Asynchronous acquisitions coordinate use of the shared refresh credential. A synchronous call reports refresh_pending while that work is in progress. A failure that may have consumed the credential can require a new login for the whole connection, even if another API token still works.

With indefinite_session = TRUE, the single module can retain usable cached tokens after such a failure, but retires the refresh credential. It cannot refresh or acquire another target without a new login. The connection manager does not have this exception. Local authenticated state alone does not prove that a selected API token is usable.