Authy API Client for Python
Python Shell Makefile
Clone or download
Latest commit 077887c Aug 5, 2018

README.md

Build Status

Python Client for Authy API

A python library for using the Authy public API.

Installation

If you have pip installed it's very easy to install authy, just type

$ pip install authy

OR

Download the source code then open a terminal and type:

$ python setup.py install

Note that you may need admin permissions to run the above commands.

Usage

To use this client you just need to import AuthyApiClient and initialize it with your API KEY

from authy.api import AuthyApiClient
authy_api = AuthyApiClient('#your_api_key')

Now that you have an Authy API object you can start sending requests.

Jump to your use case

Authy (Two-factor Authentication)

User Management

In order to send 2FA codes in your applications, you'll need to create a user.

NOTE: User is matched based on cellphone and country code not e-mail. A cellphone is uniquely associated with an authy_id. Creating the same user twice will return the same user id.

Create A User

To create a user, you need to pass an email, a cellphone, and optionally a country code:

user = authy_api.users.create('new_user@email.com', '405-342-5699', 57) #email, cellphone, country_code

In this case, 57 is the country code for Colombia. If not provided, the country code defaults to 1 for the USA.

If the request was successful, you need to store the authy id in your database. Use user.id to get this id in your database.

if user.ok():
    # store user.id in your user database
else:
	print user.errors()

If something went wrong, ok() returns False and you can see the errors. This returns a dictionary explaining what went wrong with the request.

Check A User Status

To check a user status, pass the user id.

status = authy_api.users.status(authy_id)

if status.ok():
	print status.content

# Phone number is always obfuscated in this request
# {u'status': {u'phone_number': u'XXX-XXX-1234', u'confirmed': True, u'authy_id': 123, u'registered': True, u'devices': [u'iphone', u'iphone'], u'detailed_devices': [{u'os_type': u'unknown', u'device_type': u'authy', u'creation_date': 1509063624}......

Delete A User

To delete a user, just pass the user id.

user = authy_api.users.delete(authy_id)

print user.content
# {u'message': u'User removed from application', u'success': True}

Sending SMS 2FA Tokens

To request a SMS token you need the user id.

sms = authy_api.users.request_sms(authy_id)

print sms.content
# {u'cellphone': u'+1-XXX-XXX-XX34', u'message': u'SMS token was sent', u'success': True}

As always, you can use ok() to verify if the token was sent. To be able to use this method you need to have activated the SMS plugin for your Authy App.

This call will be ignored if the user is using the Authy Mobile App (the user would instead see it as a request within the Authy Mobile App). If you still want to send the SMS pass {'force': True} as an option.

sms = authy_api.users.request_sms(authy_id, {'force': True})

If the SMS token request was ignored because the user has the Authy Mobile App, then sms.ignored() will return True.

Sending Call 2FA Tokens

To request a Call token you need the user id.

call = authy_api.users.request_call('authy-id')

print call.content
{u'cellphone': u'+1-XXX-XXX-XX34', u'message': u'Call started...', u'success': True}

As always, you can use ok() to verify if the token was sent.

This call will be ignored if the user is using the Authy Mobile App (the user would instead see it as a request within the Authy Mobile App). If you still want to call pass {'force': True} as an option.

sms = authy_api.users.request_call(authy_id, {'force': True})

Verifying Tokens

NOTE: Token verification is only enforced if the user has completed registration. To change this behaviour see Forcing Verification.

Registration is completed once the user installs and registers the Authy mobile app or logs in once successfully using SMS.

To verify users you need the user id and a token. The token you get from the user through your login form.

verification = authy_api.tokens.verify(authy_id, token_entered_by_the_user)

Once again you can use ok() to verify whether the token was valid or not.

if verification.ok():
    # the user is valid

Forcing Verification

If you wish to verify tokens even if the user has not yet completed registration, pass {'force': True} when verifying the token.

verification = authy_api.tokens.verify(authy_id, token_entered_by_the_user, {"force": True})

Push Authentication (aka "One Touch")

Push Authentication by Authy uses a very simple API consisting of two endpoints. One for creating approval requests and another to check the status of the approval request.

Send Approval Request

To generate a push approval request which user can accept or reject on Authy App

details ={}
details['username']='example@example.com'
details['location']='California, USA'
details['Account Number']='987654'

logos= [dict(res = 'default', url = 'https://example.com/logos/default.png'), dict(res = 'low', url = 'https://example.com/logos/default.png')]

hidden_details = {}
hidden_details['ip_address'] = '110.37.200.52'

user_id = "654321"
message = "Login requested for a CapTrade Bank account."
seconds_to_expire = 120

response = authy_api.one_touch.send_request(user_id,
	                                        message,
	                                        seconds_to_expire=seconds_to_expire,
	                                        details=details,
	                                        hidden_details=hidden_details,
	                                        logos=logos)

if response.ok():
    uuid = response.get_uuid()
    # do your stuff.
else:
    print response.errors()

The above request will generate the following:

Check OneTouch UUID status

If you want to check status (accepted/rejected) of OneTouch approval request UUID

status_response = authy_api.one_touch.get_approval_status(uuid)
if status_response.ok():
    # one of 'pending', 'approved', 'denied', or 'expired'
    approval_status = status.content['approval_request']['status']

else:
    print resp.errors()

OneTouch Callback implementation

To simplify the process of handling a request, you can set a callback URL in the console.

image

Phone Verification

Authy has an API to verify users via phone calls or sms. Also, user phone information can be gethered for support and verification purposes. You do not need the user ID to perform phone verification.

Phone Verification Start

In order to start a phone verification, we ask the API to send a token to the user via sms or call:

request = authy_api.phones.verification_start(phone_number, country_code, via='sms')

print request.content

# {u'uuid': u'1785f5b0-1234-1234-1234-1285ca17e122', u'success': True, u'seconds_to_expire': 587, u'is_cellphone': True, u'carrier': u'AT&T Wireless', u'message': u'Text message sent to +1 123-456-7890.'}

Optionally you can specify the language that you prefer the phone verification message to be sent. Supported languages include: English (en), Spanish (es), Portuguese (pt), German (de), French (fr) and Italian (it). If not specified, English will be used.

# This will send a message in spanish
authy_api.phones.verification_start(phone_number, country_code, via='sms', locale='es')

Phone Verification Check

Once you get the verification from user, you can check if it's valid with:

check = authy_api.phones.verification_check(phone_number, country_code, verification_code)

print check.ok()
# True

If .ok() returns false, .content() will provide useful information:

print check.content

# wrong code:
# {u'message': u'Verification code is incorrect', u'errors': {u'message': u'Verification code is incorrect'}, u'error_code': u'60022', u'success': False}

# no verifications pending:
# {u'message': u'No pending verifications for +1 231-357-6187 found.', u'errors': {u'message': u'No pending verifications for +1 123-456-7890 found.'}, u'error_code': u'60023', u'success': False}

Phone Intelligence

If you want to gather additional information about user phone, use the phone intelligence API.

phone_intel = authy_api.phones.info(phone_number, country_code)

if phone_intel.ok():
	print phone_intel.content
	
# {u'ported': False, u'message': u'Phone number information as of 2018-01-05 00:49:41 UTC', u'type': u'cellphone', u'success': True, u'provider': u'AT&T Wireless'}

Application Info

Details

To see application details, use

app = authy_api.apps.fetch()

if app.ok():
	print app.content
else:
	print app.errors()

# {u'app': {u'name': u'Sample App', u'sms_enabled': True, u'app_id': 12345, u'phone_calls_enabled': True......

Statistics

To request application statistics, use

statistics = authy_api.stats.fetch()

if statistics.ok():
    print statistics.content
else:
    print statistics.errors()
    
# {u'count': 2, u'stats': [{u'auths_count': 0, u'calls_count': 0, u'month': u'December', u'api_calls_count': 6......

Official Documentation

You can find the full API documentation in the official documentation.

Contributing

Install development dependencies with pip:

sudo pip install -r requirements.txt

To run tests:

make test

or

make testfile tests/<test_case_file>

Copyright

Copyright (c) 2011-2020 Authy Inc. See LICENSE for further details.