view  

The 3taps Data Commons

The Identity API

Conceptual Overview

The 3taps Identity API provides a centralised mechanism for keeping track of users across multiple systems. The Identity API allows users to sign up, authenticate themselves, maintain their core identity information, create profiles, and interact securely and anonymously with other users.

Client Systems

Because it is an API, the 3taps Identity system does not have a user interface of its own. Instead, it provides the underlying functionality that is used by another computer program to keep track of its users, like this:

Looked at this way, the computer program that interacts with the end user is a client of the 3taps Identity API. The various programs that make use of the Identity API are known as client systems.

Note that the 3taps Identity API is not an open API; client systems can only interact with the Identity API if they have been set up in advance, as described in the section on client systems, below.

User Authentication

Traditional computer systems have made a distinction between "signing up" for a service, and "signing in" to that service. When a user first wants to set up their account, they click on the "sign up" link, and enter various pieces of information about themselves. Then, later on, they can come back to that site and "sign in" to regain access to their account. Another typical part of this model is the "forgot your login?" link, where users can reset their passwords and even retrieve their username.

While this model works well for standalone web systems, it is now more common for users to make use of an existing authentication mechanism, such as a Twitter or Facebook ID, to sign in to a web site. For example, many web sites and online systems now have a button that looks like this:

The user simply clicks on this button, types their details into the Twitter authentication page, and clicks on a button enabling the web site to access their Twitter credentials. This allows users to use their existing Twitter login details as a way of logging in to other web sites and systems.

Using the 3taps Identity API, Client systems can support both both a traditional "sign up" process, and signing in using an existing Twitter, Facebook, Google+ or LinkedIn account. To support this, the Identity API provides three different authentication mechanisms which can be used to authenticate a user:

Note that it is up to the client systems to choose which of these authentication mechanisms they wish to support.

Sessions

Whichever mechanism is used, the end result of the authentication process is a session that allows client systems to perform various tasks on behalf of the user.

A session remains active for as long as the user stays signed in to the client system. The session can be terminated either manually (for example, when the user clicks on a Sign Out hyperlink), or automatically (for example, when the user quits the application, or after a certain period of time has elapsed).

Each session is identified by a session token that must be provided to the Identity API whenever an API call is made that affects the user's account. For example, to change the user's username, the client system must include a valid session token with the parameters sent to the identity/update API call.

User IDs

There are times when it is important to be able to uniquely identify a user. Each user in the system is given a user ID, which is a string that uniquely identifies the user. User ID strings are never re-used, and only ever apply to the user they are allocated to.


User IDs are provided by the Identity API so that they can be used by client systems to uniquely identify the logged-in user. These user IDs can also be passed to other 3taps APIs as they are needed. Note that suitably-authorized systems can pass the user ID to the /identity/get API call to retrieve the details of a user based solely on the user ID. This is only available for suitably-authorized server (ie, other parts of the 3taps system), and is not available to client systems. Any attempt to do so will result in an error being returned. Thus, client systems can only pass the user ID to other 3taps APIs -- for security reasons, client systems cannot access a user's details based on the user ID.


Core Identity

A user's core identity consists of information held about that user for the purpose of authenticating the user, and enabling interaction between users. The core identity includes the following information:

Note that all this information is optional, and a user record would typically only contain the information used to authenticate the user. For example, if a user signs up via their Twitter account, the only information to be stored would be their Twitter screen name. No other details would be stored initially at all.

A user may choose to add additional information to their core identity. For example, they may enter a name for themselves, so that the client system can display that name when the user has to choose between multiple ambiguous user records. A user may also enter alternative authentication mechanisms so they can authenticate themselves in a more convenient way, for example by supplying a username and password for subsequent login attempts. Finally, the user may supply additional information needed to support interaction, such as an email address, a mobile phone number for SMS messaging, or a credit card and/or bank account number for performing financial transactions.

In all cases, the user will only supply information that is needed to allow them to perform the tasks they wish to perform, and where they are comfortable providing this information. For example, if the user wants to receive SMS notifications when something happens within a client system, they will need to provide and verify their mobile phone number. This information will then become part of the user's core identity.

The user's core identity is also used to handle the situation where the user has forgotten their username or password; by providing additional information such as an email address of phone number, the user is able to retrieve their username, or reset their password, using these additional mechanisms to verify their identity.

Verified Identity Details

While some of the core identity details provided by the user can simply be accepted on face value (for example, when the user enters their name we simply accept whatever value they supply), other details have to be verified before they can be used. In particular:

Additional forms of validation may be added down the track.

User Profiles

While a user has a single core identity within the 3taps Identity system, they may choose to present themselves to the world in different ways, depending on what they are trying to do. Like putting on different "masks", the user can set up profiles to describe themselves in various ways:

Each user can have any number of profiles. A profile might be an accurate description of the user, it might be accurate but deliberately vague, or it might be completely fictitious. Profiles might be set up for a particular purpose, or the user might choose to set up just one profile which they use for all interactions.

The user's profiles are automatically shared across the various client systems, so that the information only needs to be set up once. A user profile can include a photo, along with additional information such as the user's full name, their location, their web site address, etc. Client systems can also define and store their own client-specific information that is stored as part of the profile.

Secure and Anonymous Interaction

Users can interact with each other, for example by sending an SMS message, an email, or by transferring funds. However, users never interact directly with one another; instead, they interact via their profiles:

This allows all interaction between users to remain anonymous -- a user may choose to reveal his or her true details, but isn't required to do so.

Internally, all interactions take place via the 3taps Identity API. This means that even client systems don't know the true identity of the user behind the profile. All that the client system knows is that they are communicating with the user with profile X; who is behind that profile remains a secret that only the profile's owner (and the Identity API) knows.

Despite this anonymity, only authenticated users can work with the 3taps Identity API, ensuring that all interactions are secure. Users may not know who they are interacting with, but we do. And because the 3taps Identity API keeps a complete record of all changes made to the user's core identity, as well as to their profiles, and all interactions that occur between users, we have a complete audit trail of everything that happens so that we can follow up if any problems do occur.

Using the 3taps Identity API

The 3taps Identity API can be accessed at the following URL:

http://identity.3taps.com

All the API calls are defined as relative URLs within this base URL. So, for example, the get_request_salt API call can be found at:

http://identity.3taps.com/client/get_request_salt

Before making an API call, a client system must authenticate itself with the 3taps Identity API. To avoid possible security breaches, the challenge/response authentication scheme is used: the Identity API provides a random "challenge" which is combined with the client's private key to yield a "response" which is then used to authenticate the client. The exact steps required to calculate this response, and how to use it, are described in the section on client authentication, below.

The API calls supported by the 3taps Identity API can be broken down into the following groups:

Each of these groups of API calls are discussed in more detail below.

The 3taps Identity API also provides a web interface where suitably-authorized people can access the system administration features of the Identity API. This administrator interface can be found at:

http://identity.3taps.com/admin

Client Authentication

As mentioned earlier, the 3taps Identity API is not an open API. Only suitably-authorized systems are allowed to interact with it. For each client system, the 3taps Identity API will store the following information:

name

A human-readable name for this client system.

code

A two-character code unique to this client system. This code is selected by a system administrator, and is used internally for logging, and for defining client-specific profile data.

system_id

A computer-generated 32-character string that uniquely identifies this client system. This acts as the client system's "public key" for authentication purposes.

private_key

A computer-generated 32-character string that is known to both the Identity API and the client system, but is never transmitted or made public. This is used for authentication purposes.

A system administrator is able to set up and modify the details of each client system. Note that this must be done before a client system is able to access the Identity API.

The client's private key is considered to be sensitive information. When a client system is set up by the system administrator, that administrator will take note of the client's private key, and transmit that key to the developers of the client system using a secure mechanism such as by storing it in a password-protected document, emailing it through to the developers, and then phoning the developers to give the password required to open that document.

Before a client system is able to issue an API call, it must authenticate itself with the 3taps Identity API in a secure manner. This is done in the following way:

  1. The client must call the client/get_request_salt endpoint to receive a 32-character salt value to use for the API call. This salt value is the "challenge" portion of the challenge/response authentication scheme.

  2. The client then concatenates the returned salt with the client's private key, and calculates an MD5 hash of the resulting string. This MD5 hash is then converted to a 32-character string of hexadecimal digits, which will be called the hash.

  3. Finally, the salt and the hash values will be concatenated together to yield a 64-character request ID. This request ID forms the "response" portion of the challenge/response authentication scheme.
For security reasons, the client's private key must never be used directly in a program running within a web browser. Javascript-based code is inherently insecure as anybody can read the source code. To ensure that the private key remains secure, any calculations which make use of the private key must be performed on a server where the source code (and hence the private key) can never be seen by an outside party.

The following Python code shows in detail how the request ID should be calculated:

    import hashlib, md5, urllib

    CLIENT_SYSTEM_ID   = "..."
    CLIENT_PRIVATE_KEY = "..."

    f = urllib.urlopen("http://identity.3taps.com/client/get_request_salt",
                       urllib.urlencode({'system_id' : CLIENT_SYSTEM_ID}))
    response = f.read()
    conn.close()

    request_salt = response.strip()
    request_hash = hashlib.md5(request_salt + CLIENT_PRIVATE_KEY).hexdigest()
    request_id   = request_salt + request_hash

Once it has been calculated, the request ID must be passed as a parameter to the desired API endpoint. If the request ID is missing or invalid, if the salt value used to calculate the request ID has already been used to make an API call, or there was more than a 30-second delay between issuing the salt value and the API call being made, the Identity API will return a 403 (forbidden) response back to the caller.

The following API call is provided to support client authentication:

http://identity.3taps.com/client/get_request_salt

Receive a salt value to use for making a request to the Identity API. This API call takes the following parameter:

system_id (required)

The client's system ID.

Upon completion, this API call will return an HTTP status code of 200 (OK) if the system ID is valid, or 400 (bad request) if there is no authorized system with that ID.

If the request was processed successfully, the body of the HTTP response will be a 32-character string to use as the request salt for an API call.

Note that request salt values can only be used once, and the API call must be made within 30 seconds of the salt value being requested, or the API call will be rejected.

In addition, the following API call can be used to test that the authentication is working:

http://identity.3taps.com/client/test_authentication

Check to see if the given request ID is acceptable. This API call takes the following parameter:

request_id (required)

The request ID used to authenticate the client system making this request.

Upon completion, this API call will return an HTTP status code of 200 (OK) if the request ID is valid, or 403 (forbidden) if the request ID was not acceptable.

No additional information is returned. This can be used to test that the client is able to make authenticated requests to the server.

User Authentication

As described above, there are three different authentication mechanisms supported by the 3taps Identity API:

Let's examine each of these authentication mechanisms in turn.

Sign-up

Signing a user up with a username and password involves the following process:

Note that, for security purposes, the actual text of the entered password is never sent across the network. Instead, a one-way-hash is calculated based on the entered password. This is done in the following way:

  1. The client system calculates a random 32-character string, called the salt value.

  2. The client then concatenates the salt value and the entered password together, and calculates an MD5 hash of the resulting string. This MD5 hash is then converted to a 32-character string of hexadecimal digits, which will be called the password_hash.

  3. The password hash, along with the salt value, is then sent to the Identity API's for processing.

The following API call is provided to support user sign-ups:

http://identity.3taps.com/user/signup

Attempt to sign the user up with the given username and password.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The username entered by the user.

password_salt (required)

The salt value used to calculate the password hash.

password_hash (required)

The hash calculated from the entered password.

Upon completion, this API call will return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the signup request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error message may be returned:

Duplicate username

There is already a user with that username.

session_token

If the request was successful, this will be the session token identifying the user's authenticated session.

Sign-in

Signing a user in with a username and password involves the following process:

Note that two security imperatives affect the design of the user sign-in process:

  1. The user's password must never be sent in plain-text form.

  2. The user can't be given "clues" if they are trying to guess a username and password. In particular, the "incorrect username or password" error message is deliberately vague, and is the same regardless of whether the user typed in an unknown username or an incorrect password.

This second imperative has been extended to prevent even the client system itself knowing if a user exists with that username -- note that the Identity API returns a "dummy" salt value if the user doesn't exist. This will cause the sign-in attempt to fail, without changing the client's workflow.


Because the same salt value is used to hash the user's password each time, it may seem that simply performing a one-way hash of the user's password is a security risk: a packet sniffer could steal the entered username and the calculated password hash, and then re-use these values to sign in as if they were that user. However, remember that each request sent to the Identity API has a unique request_id that must be recalculated each time. This prevents rogue programs from using the password hash to sign in even if they are able to obtain it.


The following API calls have been provided to support user sign-in:

http://identity.3taps.com/user/get_salt

Retrieve the "salt" value to use for hashing a user's password.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The desired username.

Upon completion, this API call will return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following field:

password_salt

The salt value to use to calculate the password hash.

Note that a salt value will always be returned, even if the given username does not exist.

http://identity.3taps.com/user/signin

Attempt to sign the user in with the given username and password.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The username entered by the user.

password_hash (required)

The hash calculated from the entered password.

Upon completion, this API call will return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the signup request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error message may be returned:

Incorrect username or password

Either the given username does not exist, or the entered password was incorrect. Note that this error message is deliberately vague.

session_token

If the request was successful, this will be the session token identifying the user's authenticated session.

Social Sign-in

All of the social networks supported by the 3taps Identity API make use of an OAuth style authentication scheme. While the exact internal details will vary between social networks, the basic process remains the same. For example, for signing in with a Twitter ID, the following steps are required:

As you can see, there is a lot of back-and-forth between the client system, the Identity API, and Twitter's own authentication API. Implementing social sign-in requires the client system to either be a web-based application, or have the ability to open a web browser within a window, and then close that window again when the appropriate callback has been made.

The following API call is provided to support social sign-in:

http://identity.3taps.com/social/signin

Start the social sign-in process.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

network (required)

The name of the social network to use for performing this social sign-in. The following social networks are currently supported:

twitter

The following networks will be supported in the future:

facebook
google+
linkedin

callback_url (required)

The URL to redirect the user back to once the sign-in process has finished. Details of this callback and how it should behave are described below.

The Identity API starts a social sign-in request with the given social network.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. There are no specific errors that can be expected to be returned -- the only errors will be if the social network is not accepting authentication requests for some reason.

redirect_url

The URL to redirect the user's web browser to.

After receiving the results back from the social_signin API call, the client system should either redirect the user's web browser to the supplied redirection URL, or open a browser window and load this URL into it. The user will then be presented with the social network's authentication page, and asked if they want to allow 3taps to access their account on that social network.

No matter what the user does, the social network will redirect the user back to an API endpoint controlled by the 3taps Identity API. The details of this endpoint are private, and will vary depending on which social network was selected.

This private API call will return an HTTP 302 ("Found") response back to the user's web browser. This will have the effect of redirecting the user back to the callback_url specified by the client system when it made the initial social_signin API call. The following HTTP "GET" query parameters will be added to the callback URL:

success

1 if the user was successfully signed in, else 0.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error message may be returned:

Authentication denied

The user rejected the authentication attempt.

session_token

If the request was successful, this will be the session token identifying the user's authenticated session.

Session Management

Once the user has authenticated themselves, the client system will be given an authenticated session token. This token is required to perform any "private" activity on behalf of the user -- for example, updating their core identity details, managing their profiles, and interacting with other users.

Session tokens remain valid for a set period of time, after which they are no longer able to be used and the user must re-authenticate themselves. Sessions can also be terminated manually (the equivalent of "logging out") by making the appropriate API call.

The following API calls are provided to support session management:

http://identity.3taps.com/session/check

Check that the given session is still valid.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the session that is being checked.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

valid

True if the session is still valid (ie, the user is still authenticated with the Identity API), otherwise false.

http://identity.3taps.com/session/signout

Sign out of the given session.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the session that is being signed out.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. Note that no additional information will be returned, regardless of the status of the given session.

The given session token will no longer be considered to be valid.

Core Identity Management

Core identity management relates to the retrieval and updating of the authenticated user's core identity details. Note that the client system is only ever able to retrieve and make changes to the core identity details for the currently-authenticated user; identity information can never be retrieved or changed unless the user has been authenticated and has a currently-valid session.

Because users occasionally forget their username or password, the core identity management also provides functionality for dealing with these situations. Of course, in this situation the user will not be able to authenticate themselves in the usual way, and so special workflows are provided to allow a user to securely retrieve their username or change their password, using a secondary mechanism (verified email address, verified phone number, social network authentication) to identify the user.

Retrieving the User's Identity Details

The following API call can be used to retrieve the current user's identity details:

http://identity.3taps.com/identity/get

Return the user's core identity details.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the user's session.

For clients calling from a specifically whitelisted IP address (ie, other servers within the 3taps system), this API call can accept the following parameter:

user_id (required)

The ID of the desired user.


Note that this option is only available for whitelisted IP addresses; client systems cannot make this API call using only the user ID.


Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error messages may be returned:

Invalid session

The given session is no longer valid.

No such user

A user ID was specified, and there is no user with that ID.

user_id

A string holding the unique ID for this user.

identity

A JSON object containing the user's core identity details. The exact set of fields provided in this object will depend on which identity details the user has set; only those fields which have been explicitly set by the user will be returned.

This object will contains some combination of the following fields:

name

The user's name, if supplied.

username

The user's username, if supplied.

password_salt

The user's current password salt, if a password has been set.

twitter_id

The user's Twitter ID (screen name), if supplied.

facebook_id

The user's Facebook ID, if supplied.

google_id

The user's Google+ ID, if supplied.

linkedin_id

The user's LinkedIn ID, if supplied.

email_address

The user's verified email address, if supplied.

phone_number

The user's verified mobile phone number, if supplied.

has_credit_card

True if and only if the user has supplied a credit card, else false. Note that for security reasons, the actual credit card details can never be retrieved.

bank_name

The name of the bank where the user's bank account is held, if supplied.

bank_address

The address of the bank branch where the account is held, if supplied.

bank_account_name

The name of the user's bank account, if supplied.

bank_account_number

The account number for the user's bank account, if supplied.

bank_sort_code

The bank's "sorting code" used for electronic fund transfers in the UK and Ireland, if supplied.

bank_routing_number

The bank's "routing transit number" used for electronic fund transfers in the USA, if supplied.

bank_swift_bic_code

The bank's "SWIFT-BIC" code (ISO 9362) used for international fund transfers, if supplied.

bank_iban_code

The bank's "IBAN" code, often used for fund transfers within the European Union, the Middle East and the Caribbean, if supplied.

Updating the User's Identity Details

When updating a user's core identity details, each piece of information has completely different requirements. For example:

Because of these varying behaviours and requirements, the Identity API only allows the client system to change one piece of information at a time. How this is done depends on the information that is being changed, as described below.

All attempts to update the user's core identity details are made by calling the http://identity.3taps.com/identity/update endpoint. The following parameters must always be supplied:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the user's session.

Additional parameters will also be needed, depending on the information to be updated. These are described below.

Upon completion, the Identity API will return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to any error messages specific to the information being updated (as described below), the API may return the following error message:

Invalid session

The given session is no longer valid.

Let's now see how the identity/update endpoint can be used to update each piece of core identity information:

Name

To update the user's name, simply provide a name parameter to the identity/update endpoint, containing the user's new name. No specific validation or error-checking is performed, as any name value is acceptable.

Username

To change or set the user's username, provide a username parameter with the user's desired username. In this case, the identity/update call may return one of the following error messages:

Invalid username

The supplied username is not acceptable.

Duplicate username

There is already a user with that username.

Password

The change the user's password, you need to provide the following parameters to the identity/update endpoint:

old_password_hash (optional)

If the user is required to enter their existing password when they change their password, this should be the one-way hash (based on the old password salt value) of the password that the user entered. Note that this is optional, and would typically be supplied only if (a) the client system requires the user to type their existing password when they set the new one, and (b) the user had previously set their password, as evidenced by the existence of the password_salt field in the identity details returned by a previous call to the get endpoint.

password_salt (required)

The user's new password salt. This should be recalculated (as a random string of 32 characters) when resetting the user's password.

password_hash (required)

A one-way hash of the entered password based on the new password salt value. Note that the process of calculating this value is described in the section on user sign-up, above.

When changing the user's password, the following error messages may be returned:

Incorrect password

If the caller supplied an old_password_hash parameter and the supplied hash did not match the existing password hash, indicating that the user typed the wrong password, this error will be returned.

Twitter ID
Facebook ID
Google+ ID
LinkedIn ID

Adding a social network ID to an existing user's identity requires the same OAuth-based workflow as required for social sign-in. In this case, the client system should issue an identity/update API call with the following additional parameters:

network (required)

The name of the social network to use for performing this social sign-in. The following social networks are currently supported:

twitter

The following social networks will be supported in the future:

facebook
google+
linkedin

callback_url (required)

The URL to redirect the user back to once the sign-in process has finished.

Upon completion, the returned JSON object will include the following additional field:

redirect_url

The URL to redirect the user's web browser to.

The callback_url and the redirect_url values should be treated in the same way as they are in the social/signin API call, described above.

Email Address

When setting or changing the user's email address, the user must verify the address before it can be accepted. The following basic workflow is used to verify an email address:

To start the process, the client system should issue an identity/update API call with an email_address parameter set to the user's email address. Note that the following error message may be returned:

Invalid email address

This will be returned if the 3taps Identity API was not able to send an email to the given address. This means that the email address was invalid or not working for some reason.

The client system should then prompt the user to enter the PIN number, and then call the following API endpoint when the PIN number has been entered:

http://identity.3taps.com/identity/verify_email

Attempt to verify the user's email address.

The following parameters are expected:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the user's session.

email_address (required)

The email address entered by the user.

pin_code

The 4-digit PIN code entered by the user.

Upon completion, the Identity API will return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic error messages, the following specific errors may be returned:

Invalid session

The given session is no longer valid.

Unknown email address

The supplied email address is not one that we've been asked to verify.

Incorrect PIN code

The user entered the wrong PIN code.

Phone Number

Setting or changing the user's phone number is very similar to the process involved in changing or setting an email address. The following basic workflow is used to verify a mobile phone number:

To start the process, the client system should issue an identity/update API call with a phone_number parameter set to the user's mobile phone number, in E.164 format. Note that the following error message may be returned:

Invalid phone number

This will be returned if the 3taps Identity API was not able to send an SMS to the given phone number. This means that the phone number was invalid (eg, not in E.164 format), or was not accepted by the SMS gateway for some reason.

The client system should then prompt the user to enter the PIN number, and then call the following API endpoint when the PIN number has been entered:

http://identity.3taps.com/identity/verify_phone

Attempt to verify the user's phone number.

The following parameters are expected:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the user's session.

phone_number (required)

The phone number entered by the user, in E.164 format.

pin_code

The 4-digit PIN code entered by the user.

Upon completion, the Identity API will return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic error messages, the following specific errors may be returned:

Invalid session

The given session is no longer valid.

Unknown phone number

The supplied phone number is not one that we've been asked to verify.

Incorrect PIN code

The user entered the wrong PIN code.

Credit Card (Not yet implemented)

To support charging against a user's credit card, the 3taps Identity API makes use of the Stripe payments system. A 3taps user who supplies a credit card will automatically be set up as a Customer in the Stripe system, and charges can be made against that customer's credit card as required.

For security reasons, the client system (and the Identity API) cannot directly capture and store credit card information. Instead, the client system should make use of either the Stripe.js javascript library (for web-based applications), or the appropriate client library for applications running on mobile devices. Whichever library the client system uses, it should make use of the Stripe functionality to collect the user's credit card details, which are stored on the Stripe server. The client system will get back an appropriate single use token which can then be passed on to the Identity API so that the credit card details can be associated with this 3taps user:

The main thing to note about this workflow is that the user's credit card details are never stored or accessed via the client system, or via 3taps. Instead, the identity details are saved directly to the Stripe server, and the Identity API sets up a Customer record on the Stripe server so that the credit card details can be used later on.

This approach ensures that the client system (and 3taps) complies with the Payment Card Industry (PCI) requirements for making credit card transactions.

Once the client system has obtained a single-use token from the Stripe library, it should pass that token to the identity/update endpoint in a parameter named credit_card_token. Note that there are no specific errors returned by the identity/update endpoint; this is because the credit card validation will already have been done by the Stripe library before it returns the single-use token.

Bank Account

The ability to associate a bank account with a user is currently quite simplistic. 3taps can store the details of the bank account, and can in theory use this information to make deposits, but there is currently no way for a user to authorise 3taps to make withdrawals from a bank account -- at present, a credit card is the only way in which charges can be imposed against a user.

To support bank transfers worldwide, the following information can be captured about a bank account:

bank_name (required)

The name of the bank where this account is held.

bank_address (required)

The address of the bank branch where the account is held. Note that this is freeform text, and not normalised in any way.

bank_account_name (optional)

The name of the bank account.

bank_account_number (required)

The account number for the bank account.

bank_sort_code (optional)

The bank's "sorting code" used for electronic fund transfers in the UK and Ireland.

bank_routing_number (optional)

The bank's "routing transit number" used for electronic fund transfers in the USA.

bank_swift_bic_code (optional)

The bank's "SWIFT-BIC" code (ISO 9362) used for international fund transfers.

bank_iban_code (optional)

The bank's "IBAN" code, often used for fund transfers within the European Union, the Middle East and the Caribbean.

To set the user's bank account details, the client system should issue an identity/update request with some combination of the above fields. The submitted details will replace the existing bank account details for the user.

Because there is no validation done on any of the bank account details, no specific error messages will be returned when setting or updating the user's bank account.

Deleting a User's Identity

A client system can delete the account for an authenticated user by issuing the following API call:

http://identity.3taps.com/identity/delete

Delete the user's core identity, and all profiles and other information associated with this user.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the user's session.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error messages may be returned:

Invalid session

The given session is no longer valid.

Note that, while deletion of the user's account is permanent, the user's complete history, along with the fact that they deleted their account, is recorded for posterity. The user cannot hide suspicious activity by deleting their account.

Handling Forgotten Usernames and Passwords

When a user authenticates by signing up, they supply their own username and password which they must use for future sign-in attempts. If a user forgets these details, the Identity API can allow a user to retrieve or reset this information using standard "forgot my username" and "forgot my password" workflows:

When the user clicks on the I forgot my username link, the client should should:

  1. Prompt the user to choose how they wish to retrieve their username:

    • By supplying an email address.

    • By supplying a phone number.

    • By signing in using a social network.

    • If the user chooses the email address option, the client system should prompt the user to enter their email address, and then call the user/retrieve_username_via_email endpoint to send the user's username to the user's email address. The user should then be prompted to enter their username and password.

    • If the user chooses the phone number option, the client system should prompt the user to enter their phone number, and then call the user/retrieve_username_via_phone endpoint to send an SMS message containing the user's username to the user's phone number. The user should then be prompted to enter their username and password.

    • If the user chooses to sign in via a social network, the client system should call the social_signin endpoint to perform an ordinary social sign-in. The user's core identity should then be retrieved using the get endpoint, and the user's username displayed before closing the current session and asking the user to enter their username and password.

When the user clicks on the I forgot my password link, the client system should:

  1. Prompt the user to enter their username, and to choose how they want to reset their password:

    • Via email.

    • Via mobile phone.

    • Via a social sign-in.

    • If the user chooses to reset their password via email, the client system should call the user/reset_password_via_email endpoint, and then prompt the user to enter the temporary password, as well as a new permanent password. The client system should then issue a user/finish_password_reset API call with the supplied username, temporary password and (hashed) permanent password.

    • If the user chooses to reset their password via mobile phone, the client system should call the user/reset_password_via_phone endpoint, and then prompt the user to enter the temporary password, as well as a new permanent password. The client system should then issue a user/finish_password_reset API call with the supplied username, temporary password and (hashed) permanent password.

    • If the user chooses to reset their password via a social network sign-in, the client system should call the social_signin endpoint to perform an ordinary social sign-in. The user should then be prompted to enter a new password, and the user/finish_password_reset endpoint should be called with the supplied username, the session_token from the social network signin, and the new (hashed) password.

The following API calls are provided to support username retrieval and password resetting:

http://identity.3taps.com/user/retrieve_username_via_email

Send the user an email with their username.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

email_address (required)

The email address entered by the user.

We check to see if there is one (and only one) user with the given email address. If so, we send an email to that address with the user's username.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error messages may be returned:

Unable to retrieve username

The username could not be retrieved via the specified email address. This can be because there isn't exactly one user with that verified email address, or because the user with that email address doesn't have a username.

http://identity.3taps.com/user/retrieve_username_via_phone

Send the user an SMS message with their username.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

phone_number (required)

The phone number entered by the user, in E.164 format.

We check to see if there is one (and only one) user with the given phone number. If so, we send an email to that address with the user's username.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error messages may be returned:

Invalid phone number

This will be returned if the 3taps Identity API was not able to send an SMS to the given phone number. This means that the phone number was invalid (eg, not in E.164 format), or was not accepted by the SMS gateway for some reason.

Ambiguous phone number

This will be returned if there is more than one user with that phone number. In this case, it is impossible to send the user's username to that phone number.

http://identity.3taps.com/user/reset_password_via_email

Create a new temporary password for a user and send that temporary password to the user's email address.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The username entered by the user.

We calculate a temporary password for this user, and send an email to the user's validated email address with that temporary password.

Note that the temporary password is in addition to, rather than replacing, the user's ordinary password. This prevents a user from entering someone else's username and forcing their password to be reset.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error messages may be returned:

Unable to send

The Identity API could not send an email to this user with instructions for resetting their password. This could be because there is no user with that username, or the user does not have a validated email address.

http://identity.3taps.com/user/reset_password_via_phone

Create a new temporary password for a user and send that temporary password to the user's phone number as an SMS message.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The username entered by the user.

We calculate a temporary password for this user, and send an SMS message to the user's validated phone number with that temporary password.

Note that the temporary password is in addition to, rather than replacing, the user's ordinary password. This prevents a user from entering someone else's username and forcing their password to be reset.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error messages may be returned:

Unable to send

The Identity API could not send an SMS to this user with instructions for resetting their password. This could be because there is no user with that username, or the user does not have a validated phone number.

http://identity.3taps.com/user/finish_password_reset

Finish resetting the user's password.

If the user has requested that a temporary password be sent to their email address or mobile phone, this endpoint should be called with the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The username entered by the user.

temp_password (required)

The temporary password as entered by the user. Note that this is sent in plain text; since the password was already sent via SMS or email, there is no additional security risk in sending this password in plain text form.

new_password_salt (required)

A random 32-character string used to perform a one-way hash of the user's new password. This should be calculated by the client system, and used for calculating the new_password_hash value, below.

new_password_hash (required)

A one-way hash of the user's new permanent password, based on the new password salt value. The process of calculating this value is described in the section on user sign-up, above.

If the user has identified themselves via a social sign-in and then entered a new permanent password, this endpoint should be called with the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

username (required)

The username entered by the user.

session_token (required)

The session token returned when the user completes their social sign-in.

new_password_salt (required)

A random 32-character string used to perform a one-way hash of the user's new password. This should be calculated by the client system, and used for calculating the new_password_hash value, below.

new_password_hash (required)

A one-way hash of the user's new permanent password, based on the new password salt value. The process of calculating this value is described in the section on user sign-up, above.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error message may be returned:

Invalid session

The given session is no longer valid.

Unknown username

There is no user with that username.

Incorrect password

The supplied temporary password entered by the user was not correct.

Wrong user

The user verified themselves using a social sign-in, but entered a different username when attempting to reset their password.

http://identity.3taps.com/user/has_secondary_authentication

Check to see if the authenticated user has supplied enough information to be able to retrieve their username or reset their password.

This can be used when displaying the user's core identity details, to prompt the user to enter more information about themselves, so that they can retrieve their username and reset their password.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token identifying this authenticated user.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. In addition to generic errors, the following specific error message may be returned:

Invalid session

The given session is no longer valid.

has_secondary_authentication

A boolean indicating whether or not the user has provided enough information to retrieve their username and/or reset their password. This will be true if and only if the user has a username and password, and either a verified email address, a verified phone number, or a verified social network ID.

Profile Management

All interactions between users take place via profiles. Profiles are always public -- that is, anybody can view a profile, though only the profile's owner is able to make changes to a profile:

To support this two-sided view of a profile, there are two different sets of API calls: one allowing anybody to view a profile, and another for an authenticated user to maintain their own profiles. Before we look at how these two "sides" of the profile world operate, let's take a closer look at the nature of the profile's data.

Profile Data

Because profiles can be shared across client systems, a profile consists of a combination of shared and client-specific data:

The shared profile data is, by definition, shared between the client systems. For this reason, the set of available fields in the shared profile data, and what each field means, has to be predefined. Client-specific profile data, on the other hand, is completely unspecified -- it is up to the client itself to choose what data to store, and how to use it.

The shared profile data consists of any combination of the following fields. Note that all this information is optional, and a user would typically only fill in the information they wish to make public.

name

The user's full name, as made public through this profile. Note that this may or may not be the user's real name.

email

The user's email address, as made public through this profile.

website

The URL used to access this user's web site, as made public through this profile.

country

Which country the user is in, as made public through this profile.

state

Which state the user is in, as made public through this profile.

metro

Which metro area the user is in, as made public through this profile.

county

Which county the user is in, as made public through this profile.

city

Which city the user is in, as made public through this profile.

locality

Which locality the user is in, as made public through this profile.

zip_code

Which ZIP code the user is in, as made public through this profile.

bio

A brief biography for this user, as made public through this profile.

description

A description to be associated with this profile.

photo

A photo to be associated with this profile. Note that the photo is uploaded as an image file, which is then scaled into three standard sizes and stored on a publically-accessible content delivery network (CDN). To set or change the profile photo, the caller should supply the image as a separate HTTP request parameter named photo. This should be an uploaded JPEG, PNG or GIF file with a maximum size of 700KB.

When retrieving the profile photo, the returned profile data will include the following three fields:

photo_url_48x48

The URL to use to access the 48x48 pixel version of the uploaded profile photo.

photo_url_72x72

The URL to use to access the 72x72 pixel version of the uploaded profile photo.

photo_url_128x128

The URL to use to access the 128x128 pixel version of the uploaded profile photo.

Viewing Profiles

As mentioned earlier, profiles are always public. Any user can view the details of any profile. There are two ways in which this "public" side of a profile can be used:

  1. A client system might identify a particular profile as being the "owner" of a resource. For example, a posting in a classified ad system might be identified as being owned by a profile.

  2. The user might then drill down and view the publically-available details of that profile.

Each profile in the 3taps Identity API has a profile_uuid which is a string that uniquely identifies this particular profile. Note that the profile UUID is completely random and has no association whatsoever with the profile's owner or any particular URL used to view that profile. For example, a profile UUID might look like this:

4b5067604a4441f9b23261136a68d071

The profile UUID can be used by a client system to associate the profile with some other resource. For example, a comment in a messaging system might have a profile UUID identifying the author of that comment.

Separately from the UUID, profiles also have a relative URL which is used to view the profile. The relative URL will be visible to the user as part of the overall URL used to view the profile. Because different client systems will customise the display of the user's profile in different ways, the exact URL will vary -- but in all cases the relative URL will form part of the URL used to access a given profile.

To see how this works, imagine that a given profile has the following relative URL:

ax74bt9/bike

In client system A, the overall URL used to view this profile might be:

http://system-A.com/profile/ax74bt9/bike

In client system B, on the other hand, the URL used to view this profile might be:

http://system-B.com/web/objects/user/ax74bt9/bike

In all cases, the profile's relative URL will form part (usually the last part) of the URL used to view the profile.

The following API calls are provided to support viewing profiles:

http://identity.3taps.com/profile/get_url

Given a profile UUID, return the relative URL to use for that profile.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

profile_uuid (required)

The UUID for the desired profile.

Note that any authenticated client system can make this request for any profile; users do not need to be authenticated (or even identify themselves) in order to view a profile.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error message may be returned:

No such profile

There is no profile with that profile UUID.

relative_url

If the request was successful, this will be a string containing the relative URL to use for this profile.

http://identity.3taps.com/profile/get

Return the contents of the given profile.

This API call can be made in two different ways, depending on whether the caller wishes to supply a profile UUID or a relative URL.

To supply a profile UUID, the following parameters must be supplied:

request_id (required)

The request ID used to authenticate the client system making this request.

profile_uuid (required)

The UUID for the desired profile.

To supply a relative URL, the following parameters must be supplied:

request_id (required)

The request ID used to authenticate the client system making this request.

relative_url (required)

The relative URL for the desired profile.

Note that any authenticated client system can make this request for any profile; users do not need to be authenticated (or even identify themselves) in order to view a profile.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error message may be returned:

No such profile

There is no profile with that UUID or relative URL.

profile

An object containing the publically-available details of this profile. This object will have the following fields:

shared_data

An object containing the field values for this profile which are shared between client systems. The exact set of fields returned depends on what shared profile data the user has suppied; the set of available fields is described in the section on profile data, above.

client_data

An object containing the field values for this profile which have been defined and set by this particular client system. The client system itself defines the set of available client-specific fields, and is responsible for setting and using these fields correctly. For more information, please refer to the section on profile data, above.

Maintaining Profiles

When a user has been authenticated, they are able to view, edit, add and delete the profiles that they own. In addition to entering the shared and client-specific data for a profile, the user can also specify the following about a profile:

tomsmith
tomsmith/bike
tomsmith/garden

The following API calls are provided to support maintaining profiles:

http://identity.3taps.com/profile/list

Return a list of this user's profiles.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

Note that only authenticated users can retrieve a list of their profiles.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error message may be returned:

Invalid session

The given session is no longer valid.

profiles

If the request was successful, this will be an array of profiles belonging to the given user. Each entry in this list will be an object with the following fields:

profile_uuid

This profile's UUID.

relative_url

The calculated relative URL for this profile.

profile_name

The name of this profile. Note that this is only returned for non-default profiles.

default

True if this is the user's default profile, else false.

anonymous

True if this profile is anonymous, else false.

shared_data

An object containing the shared field values that have been set for this profile. The set of available fields is described in the section on profile data, above.

client_data

An object containing the client-specific field values that have been set for this profile.

http://identity.3taps.com/profile/add

Add a new profile for this user.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

profile (required)

A JSON-encoded object defining the profile to add. This object should have the following fields:

profile_name (required for non-default profiles)

The name to use for the new (non-default) profile.

default (required)

True if this is to be the user's default profile, else false.

anonymous (required)

True if this profile is to be anonymous, else false.

shared_data (required)

An object containing the shared field values to set for this profile. The set of available fields is described in the section on profile data, above.

client_data (required)

An object containing the client-specific field values to set for this profile.

photo (optional)

To use an image as the profile photo, this parameter should be set to an uploaded JPEG, PNG or GIF file with a maximum size of 700KB.

Note that only authenticated users can add a profile.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The given session is no longer valid.

Profile not in JSON format

The profile parameter was not a JSON-formatted string.

Missing required 'profile_name' value

A non-default profile was supplied without a profile name.

Duplicate profile

The caller either attempted to create a second default profile for this user, or to create a non-default profile with a name that is already in use.

profile_uuid

If the request was successful, this will be the calculated UUID for the newly-added profile.

relative_url

If the request was successful, this will be the calculated relative URL for the newly-added profile.

http://identity.3taps.com/profile/update

Update the details for the given profile.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

profile_uuid (required)

The UUID for the profile to update.

changes (required)

A JSON-encoded object defining the changes to make to this profile. The following fields can be included in this object:

profile_name

The new name to use for this (non-default) profile.

default

True if this is to be the user's default profile, else false.

anonymous

True if this profile is to be anonymous, else false.

shared_data

An object containing the new shared field values to set for this profile. The set of available fields is described in the section on profile data, above.

client_data

An object containing the client-specific field values to set for this profile.

photo (optional)

To update the profile photo, this parameter should be set to an uploaded JPEG, PNG or GIF file with a maximum size of 700KB.

Note that only authenticated users can change a profile.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The given session is no longer valid.

No such profile

There is no profile with the supplied UUID value.

Not your profile

The given profile is not owned by the logged-in user.

relative_url

If the request was successful, this will be the new (calculated) relative URL for the profile.

http://identity.3taps.com/profile/delete

Delete the given profile.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

profile_uuid (required)

The UUID for the profile to delete.

Note that only authenticated users can delete a profile.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The given session is no longer valid.

No such profile

There is no profile with the supplied UUID value.

Not your profile

The given profile is not owned by the logged-in user.

User Interaction

Users are able to perform secure and anonymous interactions via profiles. The following interactions will be supported:

In addition to these interactions, the following action will be supported to, for example, top up a user's account within the client system:

The following API calls are provided to support user interaction:

http://identity.3taps.com/interaction/send_email (Not yet implemented)

Send an email message to the owner of the given profile. Note that the sender of the email can optionally be signed in, and sending the email from "behind" a profile.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (optional)

The session token for the authenticated user's session, if the user is sending an email from "behind" a profile.

from_profile_uuid (optional)

If the user is sending an email to the given profile from "behind" another profile, this should be the UUID of the profile that is sending the email. Note that this profile must be owned by the authenticated user.

return_address (optional)

If the user is not sending an email from "behind" a profile, this should be the return email address to forward replies to.

to_profile_uuid (required)

The UUID of the profile to send the email to.

subject (required)

The subject line for the email.

contents (required)

The contents of the email.

Note that anybody can send the owner of the profile an email message, either as an authenticated user sending the email from "behind" another profile, or as an unauthenticated user sending the email from a given return address.

When sending an email as an authenticated user, the following email headers will be supplied:

Sender: messages@identity.3taps.com
From: relative_url via 3taps <profile_uuid@identity.3taps.com>
Reply-To: relative_url <profile_uuid@identity.3taps.com>
To: profile_owner <owner's email address>

When sending an email as a non-authenticated user, the following email headers will be supplied:

Sender: messages@identity.3taps.com
From: sender_email via 3taps <user@identity.3taps.com>
Reply-To: sender_email <sender_email>
To: profile_owner <owner's email address>

Note that when sending email as a non-authenticated user, the sender's email address is not hidden.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The supplied session token is no longer valid.

No such profile

There is no profile with that profile UUID.

Not your profile

If the sending user is authenticated, this will be returned if the from_profile_uuid profile is not owned by the authenticated user.

Email could not be sent

An email message could not be sent to the owner of the given profile.

http://identity.3taps.com/interaction/send_sms (Not yet implemented)

Send an SMS message to the owner of the given profile. Note that you can only send an SMS message as an authenticated user who has a validated phone number to be used for replies.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

to_profile_uuid (required)

The UUID of the profile to send the SMS message to.

text (required)

The text of the SMS message.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The supplied session token is no longer valid.

No such profile

There is no profile with that profile UUID.

SMS could not be sent

An SMS message could not be sent to the owner of the given profile.

http://identity.3taps.com/interaction/send_funds (Not yet implemented)

Send some funds to the owner of the given profile.

Note that funds can only be sent if (a) the authenticated user has a validated credit card, and (b) the receiving user has specified a bank account.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

to_profile_uuid (required)

The UUID of the profile to send the funds to.

amount (required)

The amount to be transferred, as a whole number of cents in the given currency.

currency (required)

The 3-letter ISO code indicating the currency to use.

charge_description (required)

A string to appear on the owner's credit card statement for this transaction.

deposit_description (required)

A string to appear on the recipient's bank statement for this transaction.

Note that a surcharge may be imposed on the transaction to cover bank fees.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The supplied session token is no longer valid.

No such profile

There is no profile with that profile UUID.

No credit card

The authenticated user has not provided a credit card in their core identity details.

No bank account

The recipient has not specified a bank account in their core identity details.

Charge rejected

The authenticated user's credit card was not able to be debited for the desired amount.

Deposit rejected

The recipient's bank account could not be credited for this amount.

http://identity.3taps.com/interaction/charge (Not yet implemented)

Charge the authenticated user's credit card for the given amount.

Note that a credit card can only be charged if the authenticated user has a validated credit card.

This API call takes the following parameters:

request_id (required)

The request ID used to authenticate the client system making this request.

session_token (required)

The session token for the authenticated user's session.

amount (required)

The amount to be debited, as a whole number of cents in the given currency.

currency (required)

The 3-letter ISO code indicating the currency to use.

charge_description (required)

A string to appear on the owner's credit card statement for this transaction.

Note that a surcharge may be imposed to cover bank fees.

Upon completion, we return an HTTP status code of 200 (OK) if the required parameters were supplied and the request ID was accepted. In this case, the response will have a Content-Type of application/json, and the body of the response will be a JSON-formatted object with the following fields:

success

A boolean indicating whether or not the request was successful.

error

If the request was not successful, this will be a string indicating why the request failed. The following error messages may be returned:

Invalid session

The supplied session token is no longer valid.

No credit card

The authenticated user has not provided a credit card in their core identity details.

Charge rejected

The authenticated user's credit card was not able to be debited for the desired amount.