OmniAuth::FreeAgent::OAuth2

An OmniAuth strategy for authenticating with the FreeAgent API with OAuth 2.0.

Note that this gem does not yet support the Accountancy Practice API, and so cannot be used to authenticate accountancy practice users.

Installation

Add this line to your application's Gemfile:

gem "omniauth-freeagent-oauth2"

And then execute:

$ bundle

Or install it yourself as:

$ gem install omniauth-freeagent-oauth2

Usage

The FreeAgent Developer Dashboard has documentation on the FreeAgent API. To authenticate, you will need to create a Developer Dashboard account (this is not related to any other FreeAgent accounts) and create an application which will provide you with an OAuth client ID and secret. These can then be used by OmniAuth to create a provider and authenticate, which is described in more detail in the OmniAuth README.

In Rails, adding a provider looks like this in config/initializers/omniauth.rb assuming the OAuth credentials are stored as environment variables:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :freeagent,
    ENV["OMNIAUTH_FREEAGENT_CLIENT_ID"],
    ENV["OMNIAUTH_FREEAGENT_CLIENT_SECRET"]
end

With this setup, you can prompt users authenticate with FreeAgent using the correct provider by redirecting them to the appropriate endpoint in your app - in this case, /auth/freeagent. After authenticating on the FreeAgent side, /auth/freeagent/callback will be invoked with details stored in request.env['omniauth.auth'].

Below is an example of how to make an invoices request for a company after initial authentication is complete:

connection = Faraday.new(url: "https://api.freeagent.com")
connection.authorization(:Bearer, my_company_user.token)

invoice_response = connection.get("/v2/invoices", {}, {})
JSON.parse(invoice_response.body)["invoices"]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fac/omniauth-freeagent-oauth2.

Copyright

Copyright [2020] FreeAgent Central Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.