yoti 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 270442593767f8b4617061ac8ee2157e4622200f
+  data.tar.gz: f3741b80610654a97991e4152373875f044d0bf4
+SHA512:
+  metadata.gz: 9137c7fda0e3b07b02720f430dba9c2ab4996bf58865da4cd86b35284b59e2297c101d48d0323f2a61547362d0dedbe036f957e3b4ec2742beb7e04621991280
+  data.tar.gz: 846f95e71fa1bcb22f9056ed6fa8d5e1cfeee79d925693c9e7f63a206ae9678f4010dc8265811c4f6080b4fe4876a5b00858ac0ea08a13faee77e89f05d22634

data/.gitignore

@@ -0,0 +1,37 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+.env
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Ignore Yardstick measurement files
+/measurement

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## 1.0.0 - 2016-11-14
+### Added
+- This is an initial public release.
+
+## 0.1.0 - 2016-09-14
+### Added
+- This is an initial private release.

data/CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake spec` to run the tests. To install this gem onto your local machine, run `bundle exec rake install`.
+
+You can use [Guard][] to automatically run the tests every time a file in the `lib` or `spec` folder changes.
+
+
+Run Guard through Bundler with:
+
+```shell
+$ bundle exec guard
+```
+
+[Guard]: https://github.com/guard/guard
+
+## Dependencies
+
+Although this gem supports Ruby 2.0.0, in order to use the latest development dependencies you have to use at least Ruby 2.2.2.
+
+If you wish to compile `.proto` definitions to Ruby, you will need to install [Google's Protocol Buffers](http://code.google.com/p/protobuf).
+
+### OSX
+
+```shell
+$ brew install protobuf
+```
+
+### Ubuntu
+```shell
+$ sudo apt-get install -y protobuf
+```
+
+This gem relies heavily on the [Ruby Protobuf][] gem. For more information on how Google Protobuf works, please see the [Wiki pages][].
+
+Compiling the common and attribute `.proto` definitions can be done with the following commands:
+
+```shell
+$ cd lib/yoti/protobuf/v1
+$ protoc -I definitions/attribute-public-api/attrpubapi_v1 --ruby_out ./attribute_public_api definitions/attribute-public-api/attrpubapi_v1/*.proto
+$ protoc -I definitions/common-public-api/compubapi_v1/ --ruby_out ./common_public_api definitions/common-public-api/compubapi_v1/*.proto
+```
+
+These commands will overwrite the current protobuf Ruby modules, which have been modified. If the protobuf files have to be updated, a good idea would be to change them manually, or generate the files in a new location, and compare the content.
+
+[Ruby Protobuf]: https://github.com/ruby-protobuf/protobuf/
+[Wiki Pages]:    https://github.com/ruby-protobuf/protobuf/wiki
+
+## Requirements
+
+### Code coverage
+
+The 100% code coverage requirement must be met before submitting new code.
+This can be checked by opening the generated [SimpleCov][] files:
+
+ ```shell
+ $ open coverage/index.html
+ ```
+
+### Style guide
+The Ruby style guide is configured in the [rubocop.yml](rubocop.yml) file and can be checked by running:
+
+```shell
+$ bundle exec rake rubocop
+```
+
+### Documentation
+The documentation uses the [Yard][] format. Please ensure all new classes and methods are fully documented.
+
+There are a few Rake tasks to handle documentation:
+
+```shell
+$ bundle exec rake measurement
+```
+
+Verifies the documentation with [Yardstick][] and generates the `measurement/report.txt` file, containing tips on how to improve the documentation coverage.
+
+```shell
+$ bundle exec rake verify_measurements
+```
+
+Verifies that the [Yardstick][] coverage matches the one set in the [Rakefile](Rakefile).
+
+```shell
+$ bundle exec rake yard
+```
+Generates [YARD][] documentation in the doc folder.
+
+### Git
+
+Commit messages should ideally start with one of the following verbs:
+
+* Add
+* Merge
+* Fix
+* Remove
+* Improve
+* Use
+
+[SimpleCov]:   https://github.com/colszowka/simplecov
+[Yard]:        http://yardoc.org/
+[Yardstick]:   https://github.com/dkubb/yardstick
+
+## Submitting a pull request
+1. [Fork the repository.][fork]
+2. [Create a topic branch.][branch]
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake spec`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake`. If your specs fail, return to step 5.
+7. Run `open coverage/index.html`. If your changes are not completely covered
+   by your tests, return to step 3.
+8. If Rubocop warns you about styling errors, correct them based on the guidelines and run `bundle exec rake rubocop` to make sure all offences are gone.
+9. Add documentation for your feature or bug fix.
+10. Commit and push your changes.
+11. [Submit a pull request.][pr]
+
+[fork]: http://help.github.com/fork-a-repo/
+[branch]: http://learn.github.com/p/branching.html
+[pr]: http://help.github.com/send-pull-requests/

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gem 'guard'
+gem 'guard-rspec'
+gem 'pry'
+gem 'pry-byebug'
+gem 'rubocop'
+
+gemspec

data/Guardfile

@@ -0,0 +1,11 @@
+guard :rspec, cmd: 'bundle exec rspec -c -f doc' do
+  # watch /lib/ files
+  watch(%r{^lib/(.+).rb$}) do |m|
+    "spec/#{m[1]}_spec.rb"
+  end
+
+  # watch /spec/ files
+  watch(%r{^spec/(.+).rb$}) do |m|
+    "spec/#{m[1]}.rb"
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,202 @@
+terms & conditions for DEVELOPERS
+
+
+By downloading the Software (as defined below), you are accepting and agreeing to these terms and conditions (“Terms”) which constitute a legal agreement between us. If you (the Developer) do not agree with these Terms, you should not download the Software. 
+
+
+We are Yoti Limited (the “Provider”) a company registered in England and Wales. Our company registration number is 08998951 and our registered office is at 7-8 St. Martin’s Place, London WC2N 4JH. Our registered VAT number is 199947617. You can contact us by writing to us at: hello@yoti.com, or at our registered office.
+
+
+1.          Interpretation
+   1. Definitions:
+Affiliate: in relation to a party, any entity that directly or indirectly controls, is controlled by, or is under common control with a party from time to time.
+Business Day: a day other than a Saturday, Sunday or public holiday in England when banks in London are open for business.
+Control: shall be as defined in section 1124 of the Corporation Tax Act 2010, and the expression change of Control shall be construed accordingly.
+Dashboard: a web application provided by the Supplier for the benefit of an an individual or organisation, which allows those individuals or organisations to manage their Yoti accounts.  
+Developer: the individual or entity or which accepts these Terms with the Provider.
+Intellectual Property Rights: patents, utility models, rights to inventions, copyright and related rights, trade marks and service marks, business names and domain names, rights in get-up, goodwill and the right to sue for passing off or unfair competition, rights in designs, rights in computer software, database rights, rights to use, and protect the confidentiality of, confidential information (including know-how and trade secrets), and any other intellectual property rights, in each case whether registered or unregistered and including all applications and rights to apply for and be granted, renewals or extensions of, and rights to claim priority from, such rights and all similar or equivalent rights or forms of protection which subsist or will subsist now or in the future in any part of the world.
+Maintenance Release: release of the Software that corrects faults, adds functionality or otherwise amends or upgrades the Software.
+Software: the web software development kit(s) provided to the Developer by the Provider that allows individuals and entities to  communicate with the Yoti Platform and which is managed through Dashboard. 
+Yoti: the Provider’s digital identity verification system for exchanging attributes.
+   1.  Unless the context otherwise requires:
+
+
+1. A reference to a statute or statutory provision is a reference to it as amended or re-enacted. A reference to a statute or statutory provision includes any subordinate legislation made under that statute or statutory provision, as amended or re-enacted.
+
+
+1. Any phrase introduced by the terms including, include, in particular or any similar expression, shall be construed as illustrative and shall not limit the sense of the words preceding those terms.
+
+
+1. A reference to writing or written includes email. 
+2.          Basis of contract
+2.1        These Terms apply to the exclusion of any other terms that the Developer seeks to impose or incorporate, or which are implied by trade, custom, practice or course of dealing.
+   1. The parties agree that the provisions of Regulation 9 of the Electronic Commerce (EC   Directive) Regulations 2002 shall not apply to these Terms.
+3.          LICENCE
+   1. In consideration of the sum of £1 paid by the Developer to the Provider, receipt and sufficiency of which the Provider hereby acknowledges, the Provider grants to the Developer a non-exclusive, royalty-free, revocable, worldwide licence to use the Software for the duration of these Terms.
+
+
+   1. In relation to scope of use:
+
+
+1. for the purposes of clause 3.1, use of the Software shall be for the purpose only of developing applications for the exploitation of Yoti by customers of the Provider, or otherwise in accordance with the specific instructions of the Provider.
+2. the Developer may not use the Software other than as specified in clause 3.1 and clause 3.2(a).
+3. the Developer may make backup copies of the Software as may be necessary for its lawful use.
+
+
+   1. The Developer shall not:
+
+   1. sell, sub-license, assign or novate the benefit or burden of these Terms in whole or in part;
+   2. allow the Software to become the subject of any charge, lien or encumbrance; and 
+   3. deal in any other manner with any or all of its rights and obligations under these Terms.
+
+
+   1. The Developer shall:
+
+
+   1. keep a complete and accurate record of the Developer's copying and disclosure of the Software (including any back up copies made pursuant to clause 3.2(c) above) and its users, and produce such record to the Provider on request from time to time;
+   2. take all reasonable steps to prevent unauthorised copying of the Software; and
+   3. notify the Provider as soon as it becomes aware of any unauthorised use of the Software by any person.
+
+
+   1. Developer’s Affiliates may make use of the Software, and Developer may grant access to the Software to such of its employees, or contractors and consultants under the direct control of the Developer (“Developer Personnel”), as necessary provided that the Developer:
+
+
+   1. procures that its Affiliates, and Developer Personnel are made aware of and at all times adhere to these Terms;
+   2. remains liable for the acts or omissions of its Affiliates and Developer Personnel as if they were its own; and
+   3. shall cease to make the Software available to any of its Affiliates immediately on that party ceasing to be an Affiliate, and to any of its Developer Personnel on that party ceasing to be employed or engaged by the Developer.
+   1. MAINTENANCE RELEASES
+The Provider will provide the Developer with all Maintenance Releases generally made available to its customers. 
+   1. Developer's obligations 
+
+      1. The Developer represents, warrants and undertakes that it will use the Software in compliance with all applicable laws and shall not: (a) resell, sublicense, lease or otherwise make available to any third party the Software; (b) attempt to gain or gain unauthorised access to, or disrupt the integrity or performance of the Software; (c) modify, copy, translate or create derivative works based on the Software or attempt to discover the source code or underlying ideas or algorithms thereof; (d) reverse engineer, decompile or disassemble the Software; (e) use the Software for the purpose of building a competitive product or service or copying its features, technology or user interface; (f) use the Software, or permit the foregoing to be used, for purposes of product evaluation, benchmarking or other comparative analysis intended for publication without  the Provider's prior written consent; (g) act or omit to act in any way that results in damage to the Provider's business or reputation; and (h) use or otherwise deal with the Provider’s logos, as notified to the Developer from time to time, other than in accordance with these Terms. 
+      2. Any breach by the Developer of any of the provisions in clause 5.1 shall be a material breach of these Terms and, without prejudice to its other rights and remedies, shall entitle the Provider to terminate these Terms immediately on written notice to the Developer.
+      1. dashboard
+
+
+      1. The Developer may only invite, and grant access to, authorised Developer Personnel to use the Dashboard and shall procure that any such Developer Personnel only uses the Dashboard (and any information contained therein) for the purposes as specified in clause 3.1 and 3.2(a), and not for any other purpose whatsoever. 
+
+         1. Intellectual property rights 
+         1. The Developer acknowledges that all Intellectual Property Rights in or arising out of or in connection with the Software shall be owned by the Provider, and neither the Developer nor any of its Affiliates have any rights other than to use the Software in accordance with these Terms.
+         2. The Developer agrees that it will not, and will procure that its Affiliates will not, do anything which could infringe the Intellectual Property Rights of the Provider including any of the Intellectual Property Rights arising from or in connection with the Software or otherwise pursuant to the terms of these Terms.  Any and all rights not expressly granted under these Terms shall be reserved by the Provider.
+         1. Limitation of liability and indemnities: THE DEVELOPER'S ATTENTION IS PARTICULARLY DRAWN TO THIS CLAUSE
+         1. Nothing in these Terms shall limit or exclude either party’s liability for:
+(a)  death or personal injury caused by its negligence, or the negligence of its employees, agents or subcontractors; or
+         1. fraud or fraudulent misrepresentation; or
+         2. any liability which cannot be limited or excluded by applicable law.
+
+
+         1. Subject to clause 9.1, the Provider shall not be liable to the Developer, whether in contract, tort (including negligence), for breach of statutory duty, or otherwise, arising under or in connection with these Terms for:
+(a) loss of profits;
+         1. loss of sales or business;
+         2. loss of agreements or contracts;
+         3. loss of anticipated savings;
+         4. loss of use or corruption of software, data or information;
+         5. loss of damage to goodwill; and
+         6. any indirect or consequential loss.
+
+
+         1. Except as expressly provided herein, neither party makes any warranties of any kind, whether implied, statutory or otherwise which are, to the fullest extent permitted by law, excluded from these Terms. The Provider does not warrant that the use of the Software will be uninterrupted or error-free. 
+         2. Subject to clauses 8.1, 8.2 and 8.3, the Provider shall indemnify on demand and hold harmless the Developer from and against any and all losses, demands, claims, damages, costs, expenses (including reasonable legal costs and expenses) and liabilities suffered or incurred, directly or indirectly, by the Developer and/or the Developer’s Affiliates as a result of or in connection with: (a) any third party claim brought against the Developer for infringement of a third party's rights (including any Intellectual Property Rights) arising out of, or in connection with, the receipt or use of the Software by the Developer strictly in accordance with the terms of these Terms; and (b) breach of clause 11.11 and 11.12.
+         3. Subject to clauses 9.1 and 9.2, the Developer shall indemnify on demand and hold harmless the Provider, directors, officers, employees, agents and shareholders from and against any and all losses, demands, claims, damages, costs, expenses (including reasonable legal costs and expenses) and liabilities suffered or incurred, directly or indirectly, by the Provider and/or the Provider’s Affiliates as a result of or in connection with breach of clauses 5.1, 10.11 and 10.12. 
+         4. In the event of any claim under either of the indemnities in clauses 9.5 or 9.6, the indemnified party shall:
+(a)  notify the indemnifying party in writing of any such claim (stating in reasonable detail the nature of the matter and if practicable the amount claimed); and
+         1. give the indemnifying party (at the indemnifying party’s own cost) conduct of the defence of such claim and all related settlement negotiations; and
+         2. provide the indemnifying party with reasonable assistance, information, and authority necessary to act in accordance with clause 9.7(b), all out-of-pocket expenses incurred by the indemnified party in providing such assistance, information and authority to be reimbursed by the indemnifying party.
+
+
+         1. The indemnified party shall have a duty to mitigate any loss which it may incur as a result of a matter giving rise to a right of indemnification under this clause 9. 
+         2. This clause 8 shall survive termination of these Terms.
+         1. TERM AND Termination
+         1. These Terms will continue in force from the date on which the Developer accepts these Terms until terminated in accordance with this clause. 
+         2. Either party may terminate these Terms at any time without cause by giving the other party no less than 5 Business Days’ written notice.
+         3. Without limiting any other rights or remedy available to it, either party may terminate these Terms with immediate effect by giving written notice to the other party if:
+(a) the other party commits a material breach of any term of these Terms which breach is irremediable or (if such a breach is remediable) fails to remedy that breach within 30 days after being notified to do so; or
+(b) in the case of the Provider only: (i) if there is a change of Control of the Developer; or (ii) if the Developer suffers or incurs any form of insolvency or arrangement with its creditors. 
+         1. Any provision of these Terms that expressly or by implication is intended to come into or continue in force on or after termination of these Terms shall remain in full force and effect.
+
+
+         1. Termination of these Terms shall not affect any rights, remedies, obligations or liabilities of the parties that have accrued up to the date of termination, including the right to claim damages in respect of any breach of these Terms which existed at or before the date of termination.
+
+
+         1. On termination of these Terms for any reason, the Developer shall immediately cease to use the Software, and shall procure that any of its Affiliates and the Developer Personnel shall cease to use the Software, and shall permanently delete, destroy or return to the Provider (at the Provider’s option) all copies of the Software then in its possession, custody or control.
+
+
+         1. General
+
+
+         1. Waiver
+
+
+No failure or delay by a party to exercise any right or remedy provided under this agreement or by law shall constitute a waiver of that or any other right or remedy, nor shall it prevent or restrict the further exercise of that or any other right or remedy. No single or partial exercise of such right or remedy shall prevent or restrict the further exercise of that or any other right or remedy.
+
+
+         1. Rights and remedies
+
+
+Except as expressly provided in this agreement, the rights and remedies provided under this agreement are in addition to, and not exclusive of, any rights or remedies provided by law.
+
+
+         1. Entire agreement
+(a) The Agreement and the documents otherwise referred to therein contain the whole agreement between the parties relating to the subject matter hereof and supersede all prior agreements, arrangements and understandings between the parties relating to that subject matter.
+
+         1. Each party acknowledges that, in entering into these Terms, it does not rely on any statement, representation, assurance or warranty (whether it was made negligently or innocently) of any person (whether a party to these Terms or not) (Representation) other than as expressly set out in these Terms or those documents. Each party agrees that the only rights and remedies available to it arising out of or in connection with a Representation shall be for breach of contract as expressly provided in these Terms. Nothing in this clause shall limit or exclude any liability for fraud.
+
+
+         1. Variation
+
+
+No variation of these Terms shall be effective unless it is in writing and signed by the parties (or their authorised representatives).
+
+
+         1. Severance
+
+
+If any provision or part-provision of these Terms is or becomes invalid, illegal or unenforceable, it shall be deemed modified to the minimum extent necessary to make it valid, legal and enforceable. If such modification is not possible, the relevant provision or part-provision shall be deemed deleted. Any modification to or deletion of a provision or part-provision under this clause shall not affect the validity and enforceability of the rest of these Terms.
+
+
+         1. Third parties
+
+
+A person who is not a party to these Terms shall not have any rights under the Contracts (Rights of Third Parties) Act 1999 to enforce any term of these Terms, but this does affect any right or remedy of a third party which exists, or is available, apart from that Act. Notwithstanding the foregoing, any of the Provider’s Affiliates may enforce the terms of these Terms subject to and in accordance with this clause 11.6, these Terms and the Contracts (Rights of Third Parties) Act 1999.
+
+
+         1. No partnership
+
+
+Nothing in this agreement is intended to, or shall be deemed to, establish any partnership or joint venture between any of the parties, constitute any party the agent of another party, or authorise any party to make or enter into any commitments for or on behalf of any other party. Each party confirms it is acting on its own behalf and not for the benefit of any other person.
+
+
+         1. Force majeure
+
+
+Neither party shall be in breach of these Terms nor liable for delay in performing, or failure to perform, any of its obligations under these Terms if such delay or failure result from events, circumstances or causes beyond its reasonable control, and the affected party shall be entitled to a reasonable extension of the time for performing such obligations. If the period of delay or non-performance continues for twelve weeks, the party not affected may terminate these Terms by giving 7 days’ written notice to the affected party.
+
+
+         1. Notices
+
+
+(a) Any notice or other communication given to a party under or in connection with these Terms shall be in writing, addressed to that party at its registered office or such other address as that party may have specified to the other party in writing in accordance with this clause, and shall be delivered personally, or sent by pre-paid first class post or other next working day delivery service, commercial courier, or email.
+         1. A notice or other communication shall be deemed to have been received: if delivered personally, when left at the address referred to in clause 11.9(a); if sent by pre-paid first class post or other next working day delivery service, at 9.00 am on the second Business Day after posting; if delivered by commercial courier, on the date and at the time that the courier's delivery receipt is signed; or, if sent by or email, one Business Day after transmission.
+(c)The provisions of this clause shall not apply to the service of any proceedings or other documents in any legal action.
+
+11.10  Assignment and other dealings
+(a) The Provider may at any time assign, transfer, mortgage, charge, subcontract or deal in any other manner with all or any of its rights under these Terms and may subcontract or delegate in any manner any or all of its obligations under these Terms to any third party or agent.
+         1. The Developer shall not, without the prior written consent of the Provider, assign, transfer, mortgage, charge, subcontract, declare a trust over or deal in any other manner with any or all of its rights or obligations under these Terms, other than as set out herein.
+
+
+         1. Data Protection
+ (a) Each party shall comply with all applicable data protection and data privacy laws and regulations applying to any Personal Data (as defined in the UK Data Protection Act 1998) exchanged in connection with these Terms, and each party shall have established privacy policies and processes or principles to ensure that it remains at all times in compliance with such laws and regulations.
+(b) The Developer shall ensure data minimisation and follow the ICO guidance for app developers ‘Privacy in mobile apps’ as may be updated and replaced from time to time.  
+11.12 Confidentiality
+         1. Each party shall, during the term of these Terms and thereafter, keep confidential all information of a confidential nature (including trade secrets and information of commercial value) which may become known to such party from the other party and which relates to the other party or any of its Affiliates. Neither party shall use the other party’s confidential information for its own purposes (other than implementation of these Terms) nor, without the prior written consent of the other, disclose it to any third party (except its professional advisors or as may be required by any law or any legal or regulatory authority). The foregoing obligations shall not apply (or shall cease to apply) if that information: (a) is public knowledge or already known to such party at the time of disclosure; or (b) subsequently becomes public knowledge other than by breach of this licence; or (c) subsequently comes lawfully into the possession of such party from a third party. Each party shall use its reasonable endeavours to prevent the unauthorised disclosure of any such information.
+
+
+         1. No party shall make, or permit any person to make, any public announcement concerning this agreement without the prior written consent of the other parties (such consent not to be unreasonably withheld or delayed), except as required by law, any governmental or regulatory authority (including, without limitation, any relevant securities exchange), any court or other authority of competent jurisdiction.
+
+
+
+
+         1. Audit 
+The Developer acknowledges and agrees that the Provider may, at the reasonable request of the Provider, inspect and have access to such of the Developer’s personnel, facilities and books and records, relevant to the use of the Software, for the purposes of ensuring that the Developer is complying with the terms of these Terms, provided that the Provider provides reasonable advance notice to the Developer of such inspections, which shall take place at reasonable times, unless otherwise requested by any governmental or regulatory body having jurisdiction over the Provider.
+         1. Governing law and jurisdiction
+The Agreement, and any dispute or claim arising out of or in connection with it or its subject matter or formation (including non-contractual disputes or claims) shall be governed by, and construed in accordance with the law of England and Wales. The parties irrevocably agree that the courts of England and Wales shall have exclusive jurisdiction to settle any dispute or claim that arises out of or in connection with these Terms or its subject matter or formation (including non-contractual disputes or claims).

data/README.md

@@ -0,0 +1,222 @@
+# Yoti Ruby SDK
+
+
+Welcome to the Yoti Ruby SDK. This repository contains the tools you need to quickly integrate your Ruby back-end with Yoti, so that your users can share their identity details with your application in a secure and trusted way.    
+
+## An architectural view
+To integrate your application with Yoti, your back-end must expose a GET endpoint that Yoti will use to forward tokens.
+The endpoint can be configured in your Yoti Dashboard when you create/update your application. It can be found in the Integration section under the Callback URL name.
+
+The image below shows how your application back-end and Yoti integrate in the context of a Login flow.
+Yoti SDK carries out for you steps 6, 7, 8 and the profile decryption in step 9.
+
+![alt text](login_flow.png "Login flow")
+
+
+Yoti also allows you to enable user details verification from your mobile app by means of the Android (TBA) and iOS (TBA) SDKs. In that scenario, your Yoti-enabled mobile app is playing both the role of the browser and the Yoti app. Your back-end doesn't need to handle these cases in a significantly different way, but you might decide to handle the `User-Agent` header in order to provide different responses for web and mobile clients.
+
+## References
+
+* [AES-256 symmetric encryption][]
+* [RSA pkcs asymmetric encryption][]
+* [Protocol buffers][]
+* [Base64 data][]
+
+[AES-256 symmetric encryption]:   https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
+[RSA pkcs asymmetric encryption]: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
+[Protocol buffers]:               https://en.wikipedia.org/wiki/Protocol_Buffers
+[Base64 data]:                    https://en.wikipedia.org/wiki/Base64
+
+## Requirements
+
+The Yoti gem requires at least Ruby 2.0.0.
+If you're using a version of Ruby lower than 2.2.2 you might encounter issues when [Bundler][] tries to install the [Active Support][] gem. This can be avoided by manually requiring activesupport 4.2.
+
+```ruby
+gem activesupport '~> 4.2'
+```
+
+The 1.13 version of [Bundler][] (currently in release candidate stage) will sort this dependency issue automatically. More info in this [comment][] by André Arko.
+
+[comment]: https://github.com/bundler/bundler-features/issues/120#issuecomment-214514847
+[Bundler]: http://bundler.io/
+[Active Support]: https://rubygems.org/gems/activesupport/
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'yoti'
+```
+
+And then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself as:
+
+```shell
+$ [sudo] gem install yoti
+```
+
+### Ruby on Rails
+
+The gem provides a generator for the initialization file:
+
+```shell
+$ rails generate yoti:install
+```
+
+The generated initialisation file can be found in `config/initializers/yoti.rb`.
+
+Make sure the following environment variables can be accessed by your app:
+
+`YOTI_CLIENT_SDK_ID` - found on the *Integrations* settings page
+
+`YOTI_KEY_FILE_PATH` - the full path to your security key downloaded from the *Keys* settings page (e.g. /Users/developer/access-security.pem)
+
+## Configuration
+
+A minimal Yoti client initialisation looks like this:
+
+```ruby
+Yoti.configure do |config|
+  config.client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
+  config.key_file_path = ENV['YOTI_KEY_FILE_PATH']
+end
+```
+The following options are available:
+
+Config               | Required | Default              | Note
+---------------------|----------|----------------------|-----
+`client_sdk_id`      | Yes      |                      | SDK identifier generated by when you publish your app
+`key_file_path`      | Yes      |                      | Path to the pem file generated when you create your app
+`api_url`            | No       | https://api.yoti.com |
+`api_port`           | No       | 443                  |
+
+Keeping your settings and access keys outside your repository is highly recommended. You can use gems like [dotenv][] to manage environment variables more easily.
+
+[dotenv]: https://github.com/bkeepers/dotenv
+
+### Deploying to Heroku / AWS Elastic Beanstalk
+
+Although we recommend using a pem file to store your secret key, and take advantage of the UNIX file permissions, your hosting provider might not allow access to the file system outside the deployment process.
+
+If you're using Heroku or other alternative services, you can store the content of the secret key in an environment variable.
+
+Your configuration should look like this:
+
+```ruby
+Yoti.configure do |config|
+  config.client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
+  config.key = ENV['YOTI_KEY']
+end
+```
+
+Where `YOTI_KEY` is an environment variable with the following format:
+
+```
+YOTI_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEp..."
+```
+
+An easier way of setting this on Heroku would be to use the [Heroku Command Line][]
+
+```shell
+heroku config:add YOTI_KEY ="$(cat your-access-security.pem)"
+```
+
+[Heroku Command Line]: https://devcenter.heroku.com/articles/heroku-command-line
+
+## Usage
+
+### Profile retrieval
+
+When your application receives a token via the exposed endpoint (it will be assigned to a query string parameter named `token`), you can easily retrieve the user profile:
+
+```ruby
+yoti_activity_details = Yoti::Client.get_activity_details(params[:token])
+```
+
+Before you inspect the user profile, you might want to check whether the user validation was successful. This is done as follows:
+
+```ruby
+if yoti_activity_details.outcome == 'SUCCESS'
+  user_profile = yoti_activity_details.user_profile
+else
+  # handle unhappy path
+end
+```
+
+The `user_profile ` object provides a set of attributes corresponding to user attributes. Whether the attributes are present or not depends on the settings you have applied to your app on Yoti Dashboard.
+
+### Handling users
+
+When you retrieve the user profile, you receive a user ID generated by Yoti exclusively for your application. This means that if the same individual logs into another app, Yoti will assign them a different id. You can use such id to verify whether the retrieved profile identifies a new or an existing user. Here is an example of how this works:
+
+```ruby
+if yoti_activity_details.outcome == 'SUCCESS'
+  user = your_user_search_function(yoti_activity_details.user_id)
+
+  if user
+    # handle login
+  else
+    # handle registration
+  end
+else
+  # handle unhappy path
+end
+```
+
+Where `your_user_search_function` is a piece of logic in your app that is supposed to find a user, given a user_id. Regardless of wether the user is a new or an existing one, Yoti will always provide their profile, so you don't necessarily need to store it.
+
+## Running the examples
+
+The examples can be found in the [examples folder](examples).
+For them to work you will need a working callback URL that your browser can redirect to. A good way of doing this is to use [ngrok][] to expose the local development URL. The callback URL for both examples will be: `http://your-local-url.domain/profile`.
+
+The examples also use the `YOTI_APPLICATION_ID` environment variable to display the Yoti Connect button. This value can be found in your Yoti account, on the *Integrations* page, under the *Login button* section.
+
+### Ruby on Rails
+
+* rename the [.env.default](examples/rails/.env.default) file to `.env` and fill in the required configuration values
+* install the dependencies with `bundle install`
+* start the server `rails server`
+
+Visiting the `http://your-local-url.domain` should show a Yoti Connect button
+
+### Sinatra
+
+* rename the [.env.default](examples/sinatra/.env.default) file to `.env` and fill in the required configuration values
+* install the dependencies with `bundle install`
+* start the server `dotenv ./app.rb`
+
+Visiting the `http://your-local-url.domain` should show a Yoti Connect button
+
+[ngrok]:          https://ngrok.com/
+
+## API coverage
+
+* Activity Details
+    * [X] User ID
+    * [X] Profile
+        * [X] Photo `selfie`
+        * [X] Given Names `given_names`
+        * [X] Family Name `family_name`
+        * [X] Mobile Number `phone_number`
+        * [X] Date of Birth `date_of_birth`
+        * [X] Address `post_code`
+        * [X] Gender `gender`
+        * [X] Nationality `nationality`
+
+## Changelog
+
+See recent changes in the [release notes][release notes] or the [changelog](CHANGELOG.md).
+
+[release notes]: https://github.com/getyoti/ruby/releases
+
+## License
+
+The gem is available under the following [terms](LICENSE.txt).