Basics

Basics

Workspaces

tru.ID workspaces are containers for users accounts and billing accounts. There are two different kinds of workspaces you can belong to and these are:

  • If you signed up to tru.ID on your own, you will have a workspace created for you, which, by default, you are the owner of — i.e. you'll have full control of the projects and billing for this workspace.
  • If you signed up to tru.ID through an invitation from another tru.ID user, you will by default join their workspace with the access level that they have granted you — this could either be an admin or viewer. In addition, you will also have a separate workspace that you are the owner of.

You cannot create additional workspaces, but there is no limit to the number of workspaces you can be a member of.

Workspace credentials are generated as a client ID and client secret pair. These credentials allow you to access your workspace management API, for example creating Projects. These credentials do not allow you to make product API calls. You don't really need to generate these credentials if you have already had a project created and are looking to generate an access token to authenticate with when consuming the API.

Roles

There are three types of roles users could have in a workspace. These roles are as listed below:

  • Owner: There can only be on Owner for a workspace, and this owner has full access to the workspace, they can invite new users, create and delete projects, add billing methods and top up their balance.
  • Admin: Have the same privileges as Owners over all aspects of a workspace except billing. You should consider granting Admin privileges to other users who may be writing code or using the product APIs within your organisation. There are no limits on how many admins you can invite to your workspace.
  • Viewers: Will not be able to create new projects. They can create and delete their own credentials and use them to view information relating to any project in your workspace. This role is useful for users who may want an administrative/reporting overview of the usage. There are no limits on how many viewers you can invite to your workspace.

Product API calls made by members of a workspace will consume balance from your stored value account (i.e. any top-ups or API balance credits you have are consumable by members of your workspace.)

There are no constraints imposed restricting which users can share a workspace, for example users from any domain can share the same workspace.

Billing

Billing related actions can only be performed by the sole owner of the workspace.

The sequence of actions for billing is as follows:

  • First, the owner needs to add their company details.
  • Second, the owner needs to add the payment details.
  • Finally, the owner can use this added information to top up the account.

The default platform currency is API, which will change to the currency of your choosing when topping up for the first time. Please note, you will lose any unused API balance when you top up and change currency. The currency cannot be changed after the first top up, meaning any further payment methods will need to support this currency.

Projects

A tru.ID project is a method for applications to access tru.ID's APIs. A project serves two purposes:

  • To provide credentials. Each user within the workspace will need to generate their own credentials, which will also remove the need to share credentials for a project.
  • To logically group API calls. Having separate projects for specific purposes or applications increases security and improves tracking over the useage of each project.

Users have the ability to generate up to two pairs of credentials per project. Project credentials need to be used to generate authentication tokens, they cannot directly be used for making product API calls.

With the ability to create new credentials, there is also functionality to delete your credentials. This is added because we promote good security practice such as cycling credentials regularly.

Project Modes

There are three different modes a project can belong to:

  • Live: Real world checks are made via the API, with real requests being made to mobile network operator's (MNOs) systems. This mode consumes API balance whenever an API call is accepted by the platform.
  • Sandbox: The Sandbox contains the full features that the Live mode provides, but the checks made aren't sent to the MNO's systems, these checks also don't consume API balance as the purpose of the Sandbox is to help you integrate the API and for you to build automated tests against.
  • Disabled: The project is disabled, so any API requests made will fail.

Sandbox Mode

tru.ID Projects can be set to a mode of sandbox where API requests do not result in interactions with MNOs (Mobile Network Operators) and no costs are incurred. In Sandbox mode API requests and workflows follow a set of deterministic rules that can be used to facilitate development and testing.

How to Create a Project in Sandbox Mode

A project can be created using the API. See Create a Project in the API Reference.

To create a project in sandbox mode use the CLI with --mode sandbox:

$ tru projects:create "Project Name" --mode sandbox

How to Update a Project to Sandbox Mode

A project can be updated using the API. See Update a Project in the API Reference.

To update a project to sandbox mode using the tru.ID CLI, run the following command from within a directory with a tru.json configuration file:

$ tru projects:update --mode sandbox

If the tru.json is within another directory use the --project-dir flag:

$ tru projects:update --mode sandbox --project-dir /path/to/dir/with/config/file

Sandbox Rules

Outlined below are the products and associated rules when a project has a mode set to sandbox.

PhoneCheck

Sandbox rules are applied based on the phone_number value used when creating a PhoneCheck resource. Once the Check URL has been requested the resource will transition to have status and match values determined by the following rules:

phone_number Suffixmatchstatus
An even digit: (0, 2, 4 ...)trueCOMPLETED
An odd digit: (1, 3, 5 ...)falseCOMPLETED
99 falseERROR

SIMCheck

Sandbox rules are applied based on the phone_number value used when creating a SIMCheck resource. The value of no_sim_change and status will be set based on the following logic:

phone_number Suffixno_sim_changestatus
An even digit: (0, 2, 4 ...)trueCOMPLETED
An odd digit: (1, 3, 5 ...)falseCOMPLETED
99 N/AERROR

SubscriberCheck

Sandbox rules are applied based on the phone_number value used when creating a SubscriberCheck resource. Once the Check URL has been requested the resource will transition to have status and match values determined by the following rules:

phone_number Suffixmatchstatus
Even digits: (0, 2, 4 ...)trueCOMPLETED
Odd digit: (1, 3, 5 ...)falseCOMPLETED
99 falseERROR

Device Reachability

Sandbox rules are applied based on the ip (IP Address) value used when querying the reachability of a device. The responses to the HTTP GET request will be as follows:

IP Address SuffixResult MeaningHTTP Status CodePayload
Even digit: (0, 2, 4 ...)Success200JSON result
Odd digit: (1, 3, 5 ...)Not a Mobile IP Address412JSON HTTP Problem
99 MNO Not Supported400JSON HTTP Problem
Example: IP Address Ending in an Even number
$ tru coverage:reach 127.0.0.2
network_id network_name country_code supported_products
00000 Sandbox MNO ZZ Phone Check,Sim Check,Subscriber Check
Example: IP Address Ending in an Odd number
$ tru coverage:reach 127.0.0.1
API Error: Error: Request failed with status code 412 {
"type": "https://developer.tru.id/docs/reference/api-errors#not_mobile_ip",
"title": "Precondition Failed",
"status": 412,
"detail": "Not a mobile IP"
}
› Error: failed to retrieve reach: EEXIT: 1
Example: IP Address Ending in 99
$ tru coverage:reach 127.0.0.99
API Error: Error: Request failed with status code 400 {
"type": "https://developer.tru.id/docs/reference/api-errors#mno_not_supported",
"title": "Bad Request",
"status": 400,
"detail": "MNO not supported"
}
› Error: failed to retrieve reach: EEXIT: 1

Callback URLs

A callback URL is a predefined public URL that will receive a POST request when a PhoneCheck or SubscriberCheck's status reaches one of the following:

  • COMPLETED
  • EXPIRED
  • ERROR

There are two ways to define a Callback URL:

  • In your tru.ID Console You can define the Callback URL field when creating the 'Project'.

A screenshot of the Create a Project form from the tru.ID developer console. Three input fields, a Project name, the mode (Sandbox or production), and a callback url

  • Or when creating individual PhoneCheck and SubscriberCheck checks through the optional property callback_url. Note that if you specify the optional callback_url property on a product API call, the project configuration is overridden.

Requests to the Callback URL are signed following the http message signing RFC. The signature received in the request may be used by you to confirm the sender is indeed tru.ID, and the payload hasn't been tampered.

Callbacks are useful for being notified of the status of a request, as an alternative to having to query for the status with a check_id. You should ACK callbacks received by your server with a 2XX. If we receive any of: 2XX, 3XX, 4XX, or connection timeouts, we do not retry the callback. If we receive a 5XX we will retry for a maximum of 6 tries.

Please note that we do not persist EXPIRED or ERROR Checks, so you will not see requests that didn't end up as COMPLETED when querying or listing checks made (performing a GET on any product resource). If you would like to maintain a record of these, you must provide a callback_url and parse callbacks received by it.

Made withacross the 🌍
© 2021 4Auth Limited. All rights reserved. tru.ID is the trading name of 4Auth Limited.