TOTP

How to choose your integration strategy?

Discover how to integrate Multi-Factor Authentication (MFA). With TOTP authentication for an Organization within in your app in a headless way: learn the process of creating a TOTP connection for the organization and generating a TOTP challenge for the user. Gateway User Interface here

Watch the video guide

Quickstart
15 min

View example

A TOTP is a Time-based One-Time Password, which allows

The fallback content to display on prerendering

to securely access a web

The fallback content to display on prerendering

thanks to a second security factor. Indeed, after the

The fallback content to display on prerendering

logs in, he will receive a unique code by SMS or via a QR code. Once entered into the application, this code will enable the user to access the desired service. This additional security feature is becoming increasingly popular, making traditional authentication more secure, and less sensitive.

However, it is important to ensure a number of security measures, that the link is sent securely, and that the code is only usable for a short period of time.

1 Configure your first TOTP Connection

API object definitions

Organizations: An
The fallback content to display on prerendering
represents a business customer or partner in your Cryptr service.
Users: Cryptr stores
The fallback content to display on prerendering
profiles for your
The fallback content to display on prerendering
in a dedicated hosted cloud database for a specific
The fallback content to display on prerendering
.
The fallback content to display on prerendering
profile information can come from your
The fallback content to display on prerendering
directly. The sources are
The fallback content to display on prerendering
signup,
The fallback content to display on prerendering
(via
The fallback content to display on prerendering
) logins or Active Directory.

How to leverage your API key

Setting up Environment Variables

It is important that your Cryptr

The fallback content to display on prerendering

remains secret, and therefore is defined as a CRYPTR_CLIENT_SECRET environment variable at the start of your

The fallback content to display on prerendering

. The ID of your

The fallback content to display on prerendering

CRYPTR_CLIENT_ID must also be defined.

CRYPTR_ACCOUNT_DOMAIN=communitiz-app
CRYPTR_CLIENT_SECRET=79cef058-530c-4c19-a12d-ff57ff5e592b
CRYPTR_CLIENT_ID=b7bde828-4df1-4f62-9a3a-d1541a2fc9e4

danger

Cryptr does not keep the created

The fallback content to display on prerendering

, keep it with care. You can always request a new one in case of loss, or blacklist your

The fallback content to display on prerendering

in case of compromise.

info

In a dedicated environment, remember to set the CRYPTR_SERVICE_URL as an environment variable. This ensures proper communication with the service and enables customization of the service URL based on your environment.

Cryptr Service URL for dedicated instance

CRYPTR_ACCOUNT_DOMAIN=communitiz-app
CRYPTR_CLIENT_SECRET=79cef058-530c-4c19-a12d-ff57ff5e592b
CRYPTR_CLIENT_ID=b7bde828-4df1-4f62-9a3a-d1541a2fc9e4
CRYPTR_SERVICE_URL=https://my-company.authent.me

Instantiating your Cryptr Client

Here is a concrete example to illustrate how to leverage an

The fallback content to display on prerendering

cURL
Kotlin

curl -X POST ${cryptr_service_url}/oauth/token
  -d '{
    "grant_type": "client_credentials"
    "domain": "CRYPTR_ACCOUNT_DOMAIN", 
    "client_id": "CRYPTR_CLIENT_ID", 
    "client_secret": "CRYPTR_CLIENT_SECRET"
  }' 

val cryptr = Cryptr(
  accountDomain = System.getProperty(CryptrEnvironment.CRYPTR_ACCOUNT_DOMAIN.toString()),
  apiKeyClientId = System.getProperty(CryptrEnvironment.CRYPTR_API_KEY_CLIENT_ID.toString()),
  apiKeyClientSecret = System.getProperty(CryptrEnvironment.CRYPTR_API_KEY_CLIENT_SECRET.toString()),
  //Optional fields
  defaultRedirectUrl = System.getProperty(CryptrEnvironment.CRYPTR_DEFAULT_REDIRECT_URL.toString()),
  serviceUrl = System.getProperty(CryptrEnvironment.CRYPTR_SERVICE_URL.toString()),
)

Create your Users directory

When it comes to controlling access to your

The fallback content to display on prerendering

, the first step is to store your

The fallback content to display on prerendering

in a dedicated

The fallback content to display on prerendering

. This

The fallback content to display on prerendering

is specific to each

The fallback content to display on prerendering

and environment, which can either be a sandbox environment for testing and development or a default environment for production.

The fallback content to display on prerendering

can represent your enterprise customer, a public service, or association, and is identified by a strong identifier known as the

The fallback content to display on prerendering

To get started, we create a dedicated environment for each new customer, where we store all

The fallback content to display on prerendering

information and configuration settings. This is done to ensure that the actions are only delimited to that specific customer.

The environment is defined by your

The fallback content to display on prerendering

, meaning that a sandbox

The fallback content to display on prerendering

will be stored in a sandbox environment, and a production

The fallback content to display on prerendering

will be stored in a default environment.

For example, if your

The fallback content to display on prerendering

instance uses a sandbox client ID, it will only store

The fallback content to display on prerendering

in the sandbox environment and grant them authentication rights in that environment.

To learn more about sandbox and production environments and how they affect your

The fallback content to display on prerendering

, click here.

The Organization Owner

Create a new Organization with the name, and the list of email domains from the professional emails of the

The fallback content to display on prerendering

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/organizations \
  -H "Authorization: Bearer your-access-token-from-client-id-and-secret" \
  -d name="Communitiz App" \
  -d email_domains[]="communitiz.app"

val organizationResponse = cryptr.createOrganization(
  name = "My company name",
  allowedEmailDomains = setOf("my-company.com")
)

Now we get the domain of our new

The fallback content to display on prerendering

, here communitiz-app is the domain identifier. Now, each time a new

The fallback content to display on prerendering

will be created from our password-based authentication, it will be stored in a dedicated

The fallback content to display on prerendering

Create a User

We can create a

The fallback content to display on prerendering

for an

The fallback content to display on prerendering

created

cURL
Kotlin

curl -X POST '${cryptr_service_url}/api/v2/org/${org_domain}/users'
  --form 'profile[email]="emilie@communitiz-app.co"'

val userResponse = cryptr.createUser(
  orgDomain = "communitiz-app",
  email = setOf("emilie@communitiz-app.co")
)

However, it is important to consider the following error:

"422 email has already been taken": This means that a
The fallback content to display on prerendering
with this email address already exists in your project. We inform the
The fallback content to display on prerendering
that they can use another email address or invite him to connect. (The email address is used as an identifier to find a
The fallback content to display on prerendering
.)

note

You can access a

The fallback content to display on prerendering

information using either the identifier generated when they were created, or their email address.

Click here to access the API page and explore the options for

The fallback content to display on prerendering

creation

List the users of a directory from a sandbox or production environment

We can fetch the

The fallback content to display on prerendering

from this

The fallback content to display on prerendering

, please note you can fetch

The fallback content to display on prerendering

from a sandbox environment with an

The fallback content to display on prerendering

for sandbox, and

The fallback content to display on prerendering

from production with an

The fallback content to display on prerendering

for production.

cURL
Kotlin

curl "${cryptr_service_url}/api/v2/org/${org_domain}/users" \
  -d page=${page}
  -d per_page=${per_page}

val listing = cryptr.listUsers(
  orgDomain = orgDomain,
  // Optional, size of the page
  // perPage = perPage,
  // Optional your current page
  // currentPage = currentPage
)

Of course, at this time our list is empty. To see more about

The fallback content to display on prerendering

and

The fallback content to display on prerendering

, please have a look at our Organization API Reference and User API Reference. We can store the

The fallback content to display on prerendering

of our

The fallback content to display on prerendering

, and attach a password

The fallback content to display on prerendering

to this. But we need to handle the

The fallback content to display on prerendering

TOTP Connection activation

The fallback content to display on prerendering

object definitions

Organization: An
The fallback content to display on prerendering
represents a business customer or partner in your Cryptr service.
Totp Connection: A
The fallback content to display on prerendering

The fallback content to display on prerendering
represents the parameters of the
The fallback content to display on prerendering
and enable the functionality. Without it you can't use
The fallback content to display on prerendering
.

With a created

The fallback content to display on prerendering

, and an

The fallback content to display on prerendering

, we can create a

The fallback content to display on prerendering

between your

The fallback content to display on prerendering

& your customer (the

The fallback content to display on prerendering

In fact, the TOTP connection is already created by default, but is not activated. Let's see how to activate it.

cURL
Kotlin

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection \
    -d active=true

val resp = cryptr.createTotpConnection(
  orgDomain = 'communitiz-app'
)

Manage the Totp

Here are the other possible actions for managing totp

The fallback content to display on prerendering

Update the Totp Connection

This request will help you to update the Totp params.

cURL
Kotlin

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection \
  -d active=true

val resp = cryptr.updateTotpConnection(
    orgDomain = 'communitiz-app',
    active = true
)

Deactivate the Totp Connection

cURL
Kotlin

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection \
  -d active=false

val resp = cryptr.deleteTotpConnection(
    orgDomain = 'communitiz-app'
)

In fact your TOTP Connection will never be deleted. It will be deactivated.

Retrieve the Totp Connection

cURL
Kotlin

curl "${cryptr_service_url}/api/v2/org/${org_domain}/totp-connection"

val resp = cryptr.getTotpConnection(
    orgDomain = 'communitiz-app'
)

You are now able to view the params of your Totp

The fallback content to display on prerendering

2 Enroll your Users to TOTP

TOTP Enrollment

The fallback content to display on prerendering

object definitions

Organization: An
The fallback content to display on prerendering
represents a business customer or partner in your Cryptr service.
Users: Cryptr stores
The fallback content to display on prerendering
profiles for your
The fallback content to display on prerendering
in a dedicated hosted cloud database for a specific
The fallback content to display on prerendering
.
The fallback content to display on prerendering
profile information can come from your
The fallback content to display on prerendering
directly. The sources are
The fallback content to display on prerendering
signup,
The fallback content to display on prerendering
(via
The fallback content to display on prerendering
) logins or Active Directory.

With a created

The fallback content to display on prerendering

, and an

The fallback content to display on prerendering

, we can create & enroll a

The fallback content to display on prerendering

to a TOTP method.

Before users can use an MFA like the TOTP, they must be enrolled. We will see how to do it:

Enroll your users

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment \
    -d user_id='0d34d179-8a81-49e8-b572-289d0e522691'
    -d force_enroll='false'

val resp = cryptr.createTotpEnrollment(
  orgDomain = 'communitiz-app',
  userId = '0d34d179-8a81-49e8-b572-289d0e522691',
  forceEnroll = 'false'
)

info

The force_enroll param is used to re-enroll a user who used all his recovery codes. By default, a user can't re-enroll more than 5 times without human verification.

It can also be used to generate five new recovery_codes to replace the old ones.

Validate User Enrollment

After their enrollment, your users must confirm the activation of their TOTP (validate their phone number or their TOTP App). To do this, once the user has been enrolled, you have to send them the code obtained during enrolment by SMS (for SMS Method only).

Once this has been done, user should enter the code received by SMS or in his TOTP App on your app. You can then use our validation endpoint to validate the code.

cURL
Kotlin

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/validation/${user_id} \
    -d code='145632'

val resp = cryptr.createTotpEnrollment(
  orgDomain = 'communitiz-app',
  userId = '0d34d179-8a81-49e8-b572-289d0e522691',
  code = '145632'
)

TOTP Recovery code

After enrolling a user, you'll receive a payload containing a list of five recovery codes. In the form of a string, each code will be separated by a \n. These codes must be displayed to the user, who will be able to use them if he loses access to his TOTP application, phone or phone number.

info

These recovery codes must be stored as carefully as a password (they must not be divulged or stored on the same device as the TOTP application ...). Each time a recovery code is used user should re-enroll.

Moreover, they are single-use, so a user can only use recovery codes 5 times. Once this number has been exceeded, you'll need to force a new enrollment for your user to retrieve new ones (see above the force_enroll param). Finally, codes can only be used once in a 24-hour period.

3 Integrate the Totp authentication to your Application

The fallback content to display on prerendering

object definitions

Organization: An
The fallback content to display on prerendering
represents a business customer or partner in your Cryptr service.
Totp: A
The fallback content to display on prerendering
represents a link, QR code or passcode that a
The fallback content to display on prerendering
's will use as second authentication credential to access protected services.

Receive TOTP (For SMS method only)

The below call is useful only with SMS Method. For the TOTP Mobile App Method, the code is generated by the TOTP Application of the user, but in the case of the SMS Method, you have to generate the code to send to your Users.

Challenge a Totp

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/${user_id}

val createTotpChallengeResponse = cryptr.createTotpChallenge(
  orgDomain = "communitiz-app",
  userId = "c6953c8d-b416-4727-b9cb-6a681ecbd317"
)

The createTotpChallenge function takes an user_id to create a totp

The fallback content to display on prerendering

, which will create a Totp to send to your

The fallback content to display on prerendering

Validate TOTP

Validate a Totp

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/validation/${user_id} \
  -d code='124578'

val validateTotpChallengeResponse = cryptr.validateTotpChallenge(
  orgDomain = "communitiz-app",
  userId = "c6953c8d-b416-4727-b9cb-6a681ecbd317",
  code = "124578"
)

The validateTotpChallenge function takes an user_id and a code to validate a totp

The fallback content to display on prerendering

. If the challenge is validated then the authentication is successful.

info

Instead of a TOTP Code users can use their recovery codes. If a Recovery Code is used you will need to re-enroll your user.

If the five recovery codes are used, you should re-enroll your user one last time. After that if user lose his access again you will have to force the enrollment of your user. This will give your user 5 new recovery codes.

Full example of processing of results

Kotlin

// <-- Only for SMS method
val createTotpChallengeResponse = cryptr.createTotpChallenge(
  orgDomain = "communitiz-app",
  userId = "c6953c8d-b416-4727-b9cb-6a681ecbd317"
)

// You send the code to your user by SMS
code = totpChallenge.code

// -->

// You prompt a form to the user where he can enter the code
val validateTotpChallengeResponse = cryptr.validateTotpChallenge(
  orgDomain = "communitiz-app",
  userId = "c6953c8d-b416-4727-b9cb-6a681ecbd317",
  code = "124578"
)

if (validateTotpChallengeResponse.recovery_code_used == true) {
  // Re-enroll your user
} else if (validateTotpChallengeResponse.success == true) {
  // Valid ...
} else {
  // Unauthorized ...
}

After generating a Totp

The fallback content to display on prerendering

(SMS method only) you should get a code to send to your user. You should then ask the user to enter the code received by SMS or through a TOTP App. After that we check whether the

The fallback content to display on prerendering

validation was successful ("success" property) or not. If so, the totp authentication is valid. If the user has used a recovery code, you will need to enroll again immediately.

Conclusion

I hope this guide has given you a better understanding of the steps involved in totp authentication in your

The fallback content to display on prerendering

. Here is a summary of the topics covered:

Creating an
The fallback content to display on prerendering
with a name and a list of associated email domains.
The initial configuration of the totp connection to enable TOTP for your app.
The TOTP enrollment, to enroll your
The fallback content to display on prerendering
to MFA.
Totp challenge, the way to use TOTP authentication once your user is enrolled.

To test and ensure the operation of your totp authentication system, here are a few practical tips:

Use authentication and authorization scenarios in a test environment to check that the process runs smoothly.

Alternatives

If the

The fallback content to display on prerendering

prefers using their email, we offer an alternative: the

The fallback content to display on prerendering

. Find out more about this authentication method in our magic-link integration guide. So, even if the

The fallback content to display on prerendering

prefers using their email, they can still access the

The fallback content to display on prerendering

securely and conveniently.

Thank you for choosing Cryptr to simplify

The fallback content to display on prerendering

authentication.

Please do not hesitate to contact us should you require any further assistance.

API endpoint used in this guide

You can read more about

The fallback content to display on prerendering

during this guide to our API Reference.

Endpoints

POST /api/v2/organizations
Create a new organization to attach a SSO
GET /api/v2/org/:org_domain/users
Get the users listing of an organization
PUT /api/v2/org/:org_domain/totp-connection
Create a totp connection
POST /api/v2/totp-enrollment
Create a totp enrollment
POST /api/v2/totp-challenge
Create a totp challenge

TOTP

1 Configure your first TOTP Connection​

How to leverage your API key​

Setting up Environment Variables​

Instantiating your Cryptr Client​

Create your Users directory​

The Organization Owner​

Create a User​

TOTP Connection activation​

Update the Totp Connection​

Deactivate the Totp Connection​

Retrieve the Totp Connection​

2 Enroll your Users to TOTP​

TOTP Enrollment​

Enroll your users​

Validate User Enrollment​

TOTP Recovery code​

3 Integrate the Totp authentication to your Application​

Receive TOTP (For SMS method only)​

Challenge a Totp​

Validate TOTP​

Validate a Totp​

Full example of processing of results​

Conclusion​

Alternatives​

API endpoint used in this guide​

1 Configure your first TOTP Connection

How to leverage your API key

Setting up Environment Variables

Instantiating your Cryptr Client

Create your Users directory

The Organization Owner

Create a User

TOTP Connection activation

Update the Totp Connection

Deactivate the Totp Connection

Retrieve the Totp Connection

2 Enroll your Users to TOTP

TOTP Enrollment

Enroll your users

Validate User Enrollment

TOTP Recovery code

3 Integrate the Totp authentication to your Application

Receive TOTP (For SMS method only)

Challenge a Totp

Validate TOTP

Validate a Totp

Full example of processing of results

Conclusion

Alternatives

API endpoint used in this guide