OAuth2 Setup for Brightspace Data Sets

About the Redirect URI

Brightspace requires all redirect URIs to use HTTPS – http:// is not accepted. brightspaceR uses https://localhost:1410/ by default.

How the flow works: When you run bs_auth(), the package opens your browser to the Brightspace authorization page. After you authorize, Brightspace redirects to https://localhost:1410/?code=.... Since there’s no local HTTPS server listening, your browser will show a connection error – that’s expected. You simply copy the full URL from your browser’s address bar and paste it back into R. The package extracts the authorization code from the URL and exchanges it for an access token.

You can use a different redirect URI by setting the BRIGHTSPACE_REDIRECT_URI environment variable or passing redirect_uri to bs_auth(). Just make sure it matches what you registered in Brightspace exactly.

About Scopes

{#about-scopes}

Scopes control what API endpoints your application can access. Brightspace scopes follow the pattern <group>:<resource>:<action>. brightspaceR needs scopes from two tiers depending on which features you use.

datasets:bds:read datahub:dataexports:read datahub:dataexports:download users:profile:read

datasets:bds:read datahub:dataexports:read datahub:dataexports:download reporting:dataset:list reporting:dataset:fetch reporting:job:create reporting:job:list reporting:job:fetch reporting:job:download users:profile:read

bs_check_scopes()
#> i Testing API access with current token...
#> v All 4 scope checks passed.

Option A: Config file (recommended)

{#config-file}

Create a config.yml file in your project root:

default:
  brightspace:
    client_id: "your-client-id"
    client_secret: "your-client-secret"
    instance_url: "https://myschool.brightspace.com"
    redirect_uri: "https://localhost:1410/"
    scope: "datasets:bds:read datahub:dataexports:read datahub:dataexports:download reporting:dataset:list reporting:dataset:fetch reporting:job:create reporting:job:list reporting:job:fetch reporting:job:download users:profile:read"

Or use bs_config_set() to create it interactively:

bs_config_set(
  client_id = "your-client-id",
  client_secret = "your-client-secret",
  instance_url = "https://myschool.brightspace.com"
)

The config file supports environment-based profiles via the config package. Set the R_CONFIG_ACTIVE environment variable to switch profiles:

default:
  brightspace:
    client_id: "dev-id"
    instance_url: "https://dev.brightspace.com"

production:
  inherits: default
  brightspace:
    client_id: "prod-id"
    instance_url: "https://myschool.brightspace.com"

Security note: Make sure config.yml is in your .gitignore to avoid committing secrets to version control.

Option B: Environment variables

You can pass credentials directly to bs_auth(), but it’s more convenient (and safer) to store them as environment variables. Add the following to your .Renviron file:

# Open .Renviron for editing
usethis::edit_r_environ()

Then add these lines:

BRIGHTSPACE_CLIENT_ID=your-client-id-here
BRIGHTSPACE_CLIENT_SECRET=your-client-secret-here
BRIGHTSPACE_INSTANCE_URL=https://myschool.brightspace.com

Restart R for the changes to take effect.

Security note: Never commit .Renviron to version control. It should already be listed in .gitignore by default.

Credential resolution order

bs_auth() resolves each credential in this order:

1. Explicit argument (e.g., bs_auth(client_id = "..."))
2. config.yml in the working directory (if present)
3. Environment variable (e.g., BRIGHTSPACE_CLIENT_ID)

Token Caching and Refresh

Tokens are cached to disk automatically. On subsequent calls, bs_auth() will reuse the cached token and refresh it if expired – no browser interaction needed.

To force re-authentication:

bs_deauth()
bs_auth()

Non-interactive Environments (Scheduled Scripts)

For scripts that run unattended (e.g., cron jobs, scheduled ETL pipelines), use a refresh token obtained from a prior interactive session:

bs_auth_refresh(
  refresh_token = Sys.getenv("BRIGHTSPACE_REFRESH_TOKEN")
)

This exchanges the refresh token for a new access token without any browser interaction. Store the refresh token as an environment variable or in a secure secrets manager.

“No client ID found”

Make sure your environment variables are set. Check with:

Sys.getenv("BRIGHTSPACE_CLIENT_ID")

If empty, re-check your .Renviron file and restart R.

Browser doesn’t open

If you’re in an environment without a browser (e.g., RStudio Server), the authorization URL is printed to the console. Copy it into a browser on any machine, authorize, then copy the redirect URL back.

“No authorization code found in the redirect URL”

Make sure you copy the entire URL from the address bar, including the ?code=...&state=... query parameters. It should start with https://localhost:1410/.

403 Forbidden errors

Your OAuth2 app may not have the correct scopes, or the user account you authenticated with may not have permission to access Data Hub. Check:

• Run bs_check_scopes() to see which API capabilities are available.
• The registered scopes include datasets:bds:read, datahub:dataexports:read, and datahub:dataexports:download for BDS.
• For ADS access, add the reporting:* scopes listed above.
• Your Brightspace user role has the Data Hub permissions enabled (typically requires an admin or a role with “Can Access Data Hub” permission).
• The scopes registered in the Brightspace Manage Extensibility OAuth2 settings must match the scopes requested by your application.

Token expired and won’t refresh

Clear the cached token and re-authenticate:

bs_deauth()
bs_auth()