Installation

Examples

Getting the latest notes

example.js

run it

using the OAuth client credentials grant to authenticate

When running reports locally OAuth can be used to authenticate:

using the OAuth device code grant to authenticate

When running reports locally OAuth can be used to authenticate:

How it works

On first run, the API client will:

1. Prompt the user once for two intermediate DCR OAuth client IDs — one for production (.com) and one for internal/staging (.io) — and cache them at the top level of ~/.bipsyncapi under intermediateClients as { production, staging }
2. Prompt the user to select which environment (production or staging) applies to the current API hostname, and cache that choice per API hostname as intermediateClientKey ("production" or "staging"); the actual client ID is resolved at request time via the top-level intermediateClients map, so updates to the global IDs propagate to every host automatically
3. Use the resolved intermediate client to request an OAuth token with the oauth:dcr scope via the device authorization flow
4. The user will be prompted to complete authorization in their browser
5. Once authorized, fetch the list of available scopes
6. Use the oauth:dcr-scoped token to register a new OAuth client with the required scopes via Dynamic Client Registration (RFC 7591)
7. Cache the newly registered client per API hostname in ~/.bipsyncapi
8. Prompt for team ID and cache it per API hostname after successful authentication
9. Use the cached client + credentials to obtain an access token with all available scopes plus the team-specific scope
10. Use this access token to make authenticated API requests

On subsequent runs:

• The cached intermediate client selection (intermediateClientKey), registered client, and team ID are reused; the intermediate client ID itself is re-resolved each run from the top-level intermediateClients map
• To change the intermediate client IDs for production or staging, delete the top-level intermediateClients map in ~/.bipsyncapi; you'll be prompted to re-enter both on next run
• To change which environment a given API hostname uses, edit or delete the cached intermediateClientKey field under the hostname in ~/.bipsyncapi
• To change the cached team ID, edit or delete the teamId field under the hostname in ~/.bipsyncapi
• If the available scopes change in the main app, a new client will be registered via the device / DCR flow

The user approving the device code must have the OAuth Dynamic Client Registration permission enabled in the Can Access section of their Access tab in the admin app.