Skip to content
A CLI tool for obtaining JWTs from OpenId Connect providers
Go Shell
Branch: master
Clone or download

Latest commit

Latest commit 3efd9d8 Feb 18, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows add goreleaser workflow Feb 18, 2020
cmd initalise repo Feb 18, 2020
docs initalise repo Feb 18, 2020
pkg initalise repo Feb 18, 2020
.gitignore initalise repo Feb 18, 2020
.goreleaser.yml add brew and scoop config Feb 18, 2020
LICENSE initalise repo Feb 18, 2020 update readme Feb 18, 2020 initalise repo Feb 18, 2020
go.mod initalise repo Feb 18, 2020
go.sum initalise repo Feb 18, 2020
xoauth.go initalise repo Feb 18, 2020


Get OpenId Connect tokens from the command line

A demo of XOAuth in a terminal window

XOAuth provides a simple way to interact with OpenId Connect identity providers from your local CLI. Many OIDC providers only support the Authorisation Code grant - and that means running a local web server to receive the authorisation response, or using something like Postman. These can be tricky to fit into a scripted workflow in a shell.

This tool saves you time, by:

  • Helping you configure clients and manage scopes
  • Storing client secrets securely in your OS keychain
  • Managing a local web server to receive the OpenId Connect callback
  • Opening a browser to allow users to grant consent
  • Using metadata discovery to build the Authorisation Request
  • Verifying the token integrity with the providers's JWKS public keys
  • Piping the access_token, id_token and refresh_token to stdout, so you can use them in a script workflow

Supported grant types


Download the binary for your platform:

You can run the binary directly:


Or add it to your OS PATH:


mv xoauth /usr/local/bin/xoauth && chmod +x /usr/local/bin/xoauth

Alternatively you can use brew on Mac OS:

brew tap xeroapi/homebrew-taps
brew install xoauth


The easiest way to get started on Windows is to use scoop to install xoauth:

scoop bucket add xeroapi
scoop install xoauth

Quick start


  • An OpenId Connect Client Id and Secret
  • A redirect_url of http://localhost:8080/callback configured in your OpenId Connect provider's settings (you can change the port if the default doesn't suit).

Once the tool is installed, and you have configured your client with the OpenId Provider, run these two commands to receive an access token on your command line:

xoauth setup [clientName]
xoauth connect [clientName]

Command reference


Creates a new connection

xoauth setup [clientName]
# for instance
xoauth setup xero

This will guide you through setting up a new client configuration.


Adds a scope to an existing client configuration

xoauth setup add-scope [clientName] [scopeName...]
# for instance
xoauth setup add-scope xero


Removes a scope from a client configuration

xoauth setup remove-scope [clientName] [scopeName...]
# for instance
xoauth setup remove-scope xero


Replaces the client secret, which is stored in your OS keychain

xoauth setup update-secret [clientName] [secret]
# for instance
xoauth setup update-secret xero itsasecret!


Lists all the connections you have created

xoauth list

--secrets, -s - Includes the client secrets in the output (disabled by default)

xoauth list --secrets


Deletes a given client configuration (with a prompt to confirm, we're not barbarians)

xoauth delete [clientName]


Starts the authorisation flow for a given client configuration

xoauth connect [clientName]
# for instance
xoauth connect xero

--port, -p - Change the localhost port that is used for the redirect URL

# for instance
xoauth connect xero --port 8080

--dry-run, -d - Output the Authorisation Request URL, without opening a browser window or listening for the callback

# for instance
xoauth connect xero --dry-run


Output the last set of tokens that were retrieved by the connect command

xoauth token [clientName]

--refresh, `-r' - Force a refresh of the access token

# for instance
xoauth token xero --refresh

--env, -e - Export the tokens to the environment. By convention, these will be exported in an uppercase format.

# for instance
eval(xoauth token xero --env)

Global configuration

Changing the default web server port

You can modify the default web server port by setting the XOAUTH_PORT environment variable:

# for instance
XOAUTH_PORT=9999 xoauth setup


Run the doctor command to check for common problems:

xoauth doctor

xoauth stores client configuration in a JSON file at the following location:


You may want to delete this file if problems persist.

Entries in the OS Keychain

Client secrets are saved as application passwords under the common name com.xero.xoauth


  • PRs welcome
  • Be kind
You can’t perform that action at this time.