Pixelbadger Toolkit

Overview

The oauth topic provides two capabilities: acquiring an OAuth 2.0 access token using the Resource Owner Password Credentials (ROPC) grant, and managing the named profiles that store the connection settings for each OAuth endpoint.

Profiles are stored locally and referenced by name when acquiring tokens. This avoids repeating authority URLs and client credentials on every invocation.

Grant type

ROPC

Resource Owner Password Credentials. Username and password are supplied interactively at runtime.

Profile storage

Local file

Profiles are persisted in a local configuration file managed by the toolkit.

Secrets

Secure input

Passwords and client secrets are read with echo suppressed so they do not appear in the terminal.

Output

stdout token

The raw access token is printed to stdout, suitable for scripting with $() substitution.

token

Acquires an OAuth access token for the specified profile using the Resource Owner Password Credentials grant. Username is prompted on stdout; password is read silently (no echo). The access token is printed to stdout on success.

$ pbtk oauth token --profile my-api

flowchart TD CLI["pbtk oauth token\n--profile my-api"] --> LOAD["Load profile\n(authority, client-id, scope)"] LOAD --> UNAME["Prompt: Username"] UNAME --> PASS["Prompt: Password\n(silent input)"] PASS --> HTTP["POST /token\ngrant_type=password\nusername + password\nclient credentials"] HTTP --> OUT(["stdout: access_token"])

ROPC is a legacy grant. Many modern identity providers disable it by default. It requires that the application handles user credentials directly — use it only with providers and clients explicitly configured to allow it.

Option	Required	Description
`--profile`	Yes	Name of the saved OAuth profile to use for the token request

profile

Manages the named OAuth profiles used by the token command. Three sub-actions are available: add, update, and delete.

profile add

Creates a new named profile. The client secret is read silently if not supplied via the option.

$ pbtk oauth profile add --name my-api --authority https://login.microsoftonline.com/tenant-id --client-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx --scope api://my-api/.default

Option	Required	Description
`--name`	Yes	Unique profile name used when running `token`
`--authority`	Yes	OAuth authority base URI (token endpoint is derived from this)
`--client-id`	Yes	OAuth application (client) ID
`--client-secret`	No	Client secret; prompted securely if omitted
`--scope`	No	OAuth scope(s) to request; omit for providers that use a fixed scope

profile update

Updates one or more fields of an existing profile. Only the options supplied are changed; omitted options retain their current values.

$ pbtk oauth profile update --name my-api --scope api://my-api/read

Option	Required	Description
`--name`	Yes	Name of the profile to update
`--authority`	No	New authority URI
`--client-id`	No	New client ID
`--client-secret`	No	New client secret; prompted securely if omitted and the flag is present
`--scope`	No	New scope

profile delete

Removes a saved profile by name.

$ pbtk oauth profile delete --name my-api

Option	Required	Description
`--name`	Yes	Name of the profile to delete

Profile names are case-sensitive. Deleting a profile that does not exist will return an error.

Command Reference

Command	Required options	Optional options	Output
`oauth token`	`--profile`	—	Access token printed to stdout
`oauth profile add`	`--name` `--authority` `--client-id`	`--client-secret` `--scope`	Confirmation message to stdout
`oauth profile update`	`--name`	`--authority` `--client-id` `--client-secret` `--scope`	Confirmation message to stdout
`oauth profile delete`	`--name`	—	Confirmation message to stdout