_images/pinn-python-logo.png

Python library bindings for the Pinn REST API

Installation

The easiest way to install is by using PyPi, either directly or within your requirements.txt:

pip install --upgrade pinn

You can also install directly from source:

python setup.py install

Configuration

Now that you have the package properly installed, you can configure the library with your Pinn secret key. If you don’t have access, first reach out to sales@pinn.ai.

You may set the secret_key value directly (convenient for shell testing), but typically you should set PINN_SECRET_KEY as an environmental variable for the package to pick up automatically.

Directly set the key like so:

>>> import pinn
>>> pinn.secret_key = 'sk_H5dqd648Ix9vJ7J70NjRlhXyP6AouUx8'

Or, set your environment variable for the library to autoload:

$ export PINN_SECRET_KEY=sk_H5dqd648Ix9vJ7J70NjRlhXyP6AouUx8

Now you’re all set to start making API calls.

Basics

The library is very straightforward to use. Each resource has at minumum one of the following CRUDL methods:

  • create()

  • retrieve()

  • update()

  • delete()

  • list()

For example to create a new Pinn user:

>>> user = pinn.User.create()
>>> user.user_id
'usr_zsWljQAN7p6hBbbi15FXXUJp'

Some time later we can get retrieve the user like so:

>>> user = pinn.User.retrieve(user_id='usr_zsWljQAN7p6hBbbi15FXXUJp')
>>> user.created_at
1553984207

Some resources like a User can be updated:

# You can update the user without retrieving
>>> user = pinn.User.update(user_id='usr_zsWljQAN7p6hBbbi15FXXUJp',
                            metadata={'external_id': 'ypf3JZpTB5DfByiZt'})
>>>
# Or if you already have a User object on hand, you can update the property directly and save
>>> user.metadata = {'external_id': 'ypf3JZpTB5DfByiZt'}
>>> user.save()

All resources created under your environment can be deleted, use with extreme caution:

# Delete the resource when you have an ID on hand
>>> pinn.User.delete(user_id='usr_zsWljQAN7p6hBbbi15FXXUJp')
True
# or delete the resource if you already have it on hand
>>> user.delete()
True

Finally listing resources in reverse chronological order:

>>> pinn.User.list()

Production Checklist

Once everything is working, take a glance at our checklist here to make sure your implementation is up to snuff.

  • Pinn secret_key value is stored securely on a server and never in version control

  • Pinn ID tokens are always verified before claims are trusted

  • Enrollment keys are only issued once user has sufficient privledge within your system

  • Pinn errors are all handled for

  • The Pinn User ID is mapped to my User resource in a persistent datastore

API Reference

pinn.secret_key = None

The Pinn secret key value, used to authenticate API requests.

Type

str

pinn.api_host = 'https://pinnapis.com'

Pinn API host, defaults to production Pinn-hosted service.

Type

str

pinn.api_version = None

Pinn API verision string, set this to use a specific API version.

Type

str

Resources

User

class pinn.User(response)[source]

User resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

user_id

Unique ID for the user

Type

str

created_at

Unix timestamp in seconds for when the user was created

Type

int

updated_at

Unix timestamp in seconds for when the user was last updated

Type

int

authenticated_at

Unix timestamp in seconds for when the user last authenticated

Type

int

device_enrolled

True if the user has at least 1 enrolled device

Type

bool

left_palm_enrolled

True if the user has enrolled their left palm

Type

bool

right_palm_enrolled

True if the user has enrolled their right palm

Type

bool

metadata

Arbitrary key/value data attached to the user

Type

dict

classmethod create(metadata=None)[source]

Create a new Pinn user.

Parameters

metadata (dict, optional) – The ID of the Pinn user being authorized to enroll.

Returns

The newly created user

Return type

User

Raises
classmethod delete(user_id)[source]

Update a Pinn user.

Parameters

user_id (str) – The ID of the Pinn user to delete.

Returns

A Deleted response

Return type

bool

Raises
classmethod retrieve(user_id)[source]

Retrieve a Pinn user.

Parameters

user_id (str) – The ID of the Pinn user to query.

Returns

A User resource

Return type

User

Raises
classmethod update(user_id, metadata, status)[source]

Update a Pinn user.

Parameters

  • user_id (str) – The ID of the Pinn user to update.

  • metadata (dict, optional) – Metadata to update

  • status (str, optional) – User status to update

Returns

A User resource

Return type

User

Raises

App

class pinn.App(response)[source]

App resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

app_id

Unique ID for the app

Type

str

created_at

Unix timestamp in seconds for when the app was created

Type

int

updated_at

Unix timestamp in seconds for when the app was last updated

Type

int

publishable_key

Non-secret key that is embedded to configure the SDK

Type

str

app_type

Either ios, android or web

Type

str

name

Name of the app

Type

str

description

Optional app description text

Type

str

classmethod create(app_type, name, description=None)[source]

Create a new Pinn iOS/Android/Web app.

Parameters

  • app_type (str) – Either ios, android or web

  • name (str) – Human readable name for the app

  • description (str, optional) – Descriptive text for the app

Returns

Newly created app resource

Return type

App

Raises
classmethod delete(app_id)[source]

Delete a Pinn iOS/Android/Web app.

Note

This may break your integration if app is currently in use live.

Parameters

app_id (str) – ID of the app to delete.

Returns

A deleted response

Return type

Deleted

Raises
classmethod retrieve(app_id)[source]

Retrieve a Pinn iOS/Android/Web app.

Parameters

app_id (str) – ID of the app to query.

Returns

The queried app resource

Return type

App

Raises

Device

class pinn.Device(response)[source]

Device resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

device_id

Unique ID for the device

Type

str

user_id

ID of the user the device is registered to

Type

str

created_at

Unix timestamp in seconds for when the app was created

Type

int

updated_at

Unix timestamp in seconds for when the app was last updated

Type

int

name

Human readable name of the device

Type

str

make

Manufacturer make of the device

Type

str

model

Model identifier of the device

Type

str

platform

Either ios or android

Type

str

platform_version

Last recorded platform version of the device

Type

str

framework_version

Last recorded framework version for the device

Type

str

push_notification_token

Device APNS or FCM push notification token

Type

str, optional

classmethod retrieve(device_id)[source]

Retrieve a specific key for a given user.

Event

class pinn.Event(response)[source]

Event resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

event_id

Unique ID for the event

Type

str

created_at

Unix timestamp in seconds for when the app was created

Type

int

data

Underlying data for the event

Type

dict

request

ID of the request this event corresponds to

Type

str

event_type

The type of the event that occured

Type

str

livemode

True if the event occured outside of sandbox environment

Type

bool

Log

class pinn.Log(response)[source]

Log resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

log_id

Unique ID for the log

Type

str

user_id

ID of the user that authenticated

Type

str

device_id

ID of the device that authenticated

Type

str

app_id

ID of the mobile app that was involved

Type

str

web_app_id

ID of web app that was involved

Type

str, optional

created_at

Unix timestamp in seconds for when the app was created

Type

int

success

True if authentication was successful

Type

bool

score

Combined score for all scorable biometrics

Type

float

factors

Breakdown of all factors used an their score if applicable

Type

dict

auth_type

Either web or mobile

Type

str

WebhookEndpoint

class pinn.WebhookEndpoint(response)[source]

Webhook endpoint resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

webhook_endpoint_id

Unique ID for the webhook endpoint

Type

str

created_at

Unix timestamp in seconds for when the key was created

Type

int

created_at

Unix timestamp in seconds for when the key was updated

Type

int

status

The status of the webhook endpoint

Type

str

url

Fully qualified endpoint URL where webhook events are delivered to

Type

str

events

The list of events this webhook is subscribed to

Type

list

livemode

True if webhook endpoint is in live environment

Type

bool

secret

A secret to authenticate the enroll request from Pinn mobile SDK

Type

str

EnrollmentKey

class pinn.EnrollmentKey(response)[source]

Enrollment Key resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

enrollment_key_id

Unique ID for this enrollment key

Type

str

user_id

ID of the user who the key corresponds to

Type

str

created_at

Unix timestamp in seconds for when the key was created

Type

int

expires_at

Unix timestamp in seconds for when the key will expire

Type

int

livemode

True if enrollment key is in live environment

Type

bool

secret

A secret to authenticate the enroll request from Pinn mobile SDK

Type

str

classmethod create(user_id)[source]

Create a new enrollment key for a given user.

This key is used as proof that your system is authorizing a given Pinn user to enroll. You MUST ensure proper trust is established between the user and your service before performing this operation.

Parameters

user_id (str) – The ID of the Pinn user being authorized to enroll.

Returns

A special purpose key to authorize enrollment

Return type

EnrollmentKey

Raises

RecoveryKey

class pinn.RecoveryKey(response)[source]

Recovery key resource and interface.

response

Underlying dictionary response

Type

dict

object

Identifier for the resource

Type

str

recovery_key_id

Unique ID for this recovery key

Type

str

user_id

ID of the user who the key corresponds to

Type

str

created_at

Unix timestamp in seconds for when the key was created

Type

int

expires_at

Unix timestamp in seconds for when the key will expire

Type

int

livemode

True if recovery key is in live environment

Type

bool

secret

A secret to authenticate the recovery request from Pinn mobile SDK

Type

str

flow

The auth flow required for recovery

Type

list

classmethod create(user_id, flow)[source]

Create a new recovery key for a given user.

Parameters

  • user_id (str) – ID of user to create the recovery key for.

  • flow (list, optional) – List of remote factors to check prior to re-enrollment

Returns

The newly created recovery key

Return type

RecoveryKey

Raises

Errors

exception pinn.errors.APIConnectionError(response)[source]

The Pinn host is unreachable, you can and should retry this request

exception pinn.errors.APIError(response)[source]

An internal server error caused the request to fail.

Pinn is automatically notified if issues are encountered that are internal to our service. You should retry this request in case the error was intermittent.

exception pinn.errors.AuthenticationError(response)[source]

The secret key set is invalid and cannot be used to authenticate your request.

exception pinn.errors.ConfigurationError[source]

This error is thrown fast if the library is misconfigured.

For example, if you attempt to call the library without a secret_key value set a ConfigurationError will be thrown.

exception pinn.errors.ForbiddenError(response)[source]

This error is returned if you attempt to access a resource you don’t own.

Do not attempt to retry this error, and if you receieve this error it likely means you have an incorrect secret_key set on the library.

exception pinn.errors.IDTokenVerificationError[source]

This exception can be raised during an attempt to verify an ID token.

Potentially this can be from:

  • An invalid JWT signature

  • Missing required claims

  • amr claim mismatch from expectations

exception pinn.errors.InvalidRequestError(response)[source]

The request was malformed and could not be understood by the server.

This could mean that an incorrect type was sent for a parameter, an invalid HTTP method was used or that the resource you are requesting does not exist. Do not attempt to retry the request.

exception pinn.errors.PinnError(response)[source]

Base exception class for a Pinn API Error.

static from_response(response)[source]

Create an error of the right PinnError subclass from an API response.

exception pinn.errors.RateLimitError(response)[source]

The API rate limit has been exceeded.

You should attempt to retry this request after some time has passed.

exception pinn.errors.RequestFailedError(response)[source]

The request was properly formed with valid syntax, but could not be performed.

This occurs in scenarios where circumstances prevent an operation from being executed, typically this can be situations like invalid resource state to perform the op.

Utilities

class pinn.utils.IDToken[source]

Provides functionality for verifying an incoming Pinn ID token.

static verify(id_token, amr)[source]

Verify a new incoming Pinn ID token value.

Parameters

  • id_token (str) – The ID Token received from a Pinn SDK

  • amr (list) – List of required authentication methods required

Returns

A dictionary of the verified claims

Return type

dict

Other

pinn.healthy()[source]

Perform a health check against the configured Pinn host.

Returns

True if host is available, False otherwise

Return type

bool

Indices and tables