A magical envelope with a wand of power and a key emerging from within.

Magic Link

How to choose your integration strategy?

Discover how to integrate Magic Link authentication for an Organization within in your app in a headless way: learn the process of creating a Magic Link connection for the organization and generating a Magic Link challenge for the user. Or use ready to use interface with the self-hosted Gateway User Interface here

Watch the video guide

Quickstart
15 min

View example

The fallback content to display on prerendering

is a unique login link, which allows

The fallback content to display on prerendering

to securely access a web

The fallback content to display on prerendering

without having a password. Instead, the

The fallback content to display on prerendering

receives a unique link via email or other means, which when clicked automatically logs them in. These login links are becoming increasingly popular as a more secure and convenient alternative to traditional username and password authentication, as they are less susceptible to phishing attacks and do not require

The fallback content to display on prerendering

to remember complex passwords.

However, it is important to ensure a number of security measures, that the link is sent securely, and that the

The fallback content to display on prerendering

has appropriate measures in place to protect

The fallback content to display on prerendering

accounts from unauthorized access.

1 Configure your first Magic Link 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

(coming soon)

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 allowed_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

Magic Link Connection creation

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.
Magic Link 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

Create a new

The fallback content to display on prerendering

type.

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection

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

info

Note that there is a find_or_create_user option. Thanks to this option, you can ask to create the user at the time of login. To do so, set this option to true. If you do not wish to create a user at the same time as the login, leave this option set to false or leave it blank. The default setting is true.

Manage the Magic Link

Here are the other possible actions for managing

The fallback content to display on prerendering

Update the Magic Link Connection

This request will help you to update the

The fallback content to display on prerendering

params.

cURL
Kotlin

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection \
  -d find_or_create_user=true

val resp = cryptr.updateMagicLinkConnection(
    orgDomain = 'communitiz-app',
    findOrCreateUser = true
)

Delete the Magic Link Connection

cURL
Kotlin

curl -X DELETE ${cryptr_service_url}/api/v2/org/${org_domain}/magic-link-connection

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

If you want to disable the

The fallback content to display on prerendering

on your services, you can delete the

The fallback content to display on prerendering

Retrieve the Magic Link Connection

cURL
Kotlin

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

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

You are now able to view the params of your

The fallback content to display on prerendering

2 Integrate the Magic Link 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.
Magic Link: A
The fallback content to display on prerendering
represents is a link that a
The fallback content to display on prerendering
's will use as authentication credential to access protected services.

Challenge a Magic Link

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/magic-link-challenge \
   -d user_email="emilie@communitiz-app.co" \
   -d redirect_uri="https://authent.me/welcome-back"

val createMagicLinkChallengeResponse = cryptr.createMagicLinkChallenge(
  userEmail = "john@communitiz-app.com",
  redirectUri = "https://authent.me/welcome-back"
)

The user_email domain is used to retrieve your organization domain but you can also use this endpoint with the org_domain as paramater.

Magic Link Challenge using Organization Domain

Magic Link Challenge with Org Domain

This request will help you to Challenge the

The fallback content to display on prerendering

if you can't only use the user_email.

cURL
Kotlin

curl -X POST ${cryptr_service_url}/api/v2/magic-link-challenge \
  -d user_email="emilie@communitiz-app.co" \
  -d org_domain=${org_domain} \
  -d redirect_uri="https://authent.me/welcome-back"

val createMagicLinkChallengeResponse = cryptr.createMagicLinkChallenge(
  userEmail = "john@communitiz-app.com",
  orgDomain = "communitiz-app",
  redirectUri = "https://authent.me/welcome-back"
)

The createMagicLinkChallenge function takes an email address to create a

The fallback content to display on prerendering

, which will create a

The fallback content to display on prerendering

to send to your

The fallback content to display on prerendering

info

We are using email to find the

The fallback content to display on prerendering

, the email

The fallback content to display on prerendering

helps Cryptr to find the

The fallback content to display on prerendering

owner, and that email

The fallback content to display on prerendering

is recommended for the creation of an
The fallback content to display on prerendering
. That's why the

The fallback content to display on prerendering

domain is an optional parameter.

Full example of processing of results

cURL
Kotlin

  curl -X POST ${cryptr_service_url}/api/v2/magic-link-challenge \
    -d user_email="emilie@communitiz-app.co" \
    -d redirect_uri="https://authent.me/welcome-back" \
    # OPTIONAL -d org_domain=${org_domain}

  ## This will create a Magic Link to send to your user
  ## Once your user will click on this link he will be redirected to
  ## your redirect URI and a code will be present in the params
  ## You can then use:

  ## For example: https://authent.me/welcome-back/?code=code
  curl -X POST ${cryptr_service_url}/oauth/token \
    -d code={code} \
    -d grant_type="authorization_code"

val createMagicLinkChallengeResponse = cryptr.createMagicLinkChallenge(
  userEmail = "john@communitiz-app.com",
  orgDomain = "communitiz-app",
  redirectUri = "https://authent.me/welcome-back"
)

// CALLBACK

val callbackResp = cryptr.validateMagicLinkChallenge(call.parameters.get("code"))
if (callbackResp is APISuccess) {
    val challengeResponse = callbackResp.value
    // Handle the response as you want
} else {
    // Error occurend while validating
}

After generating a

The fallback content to display on prerendering

, we check whether the

The fallback content to display on prerendering

was successful ("success" property) or not. If so, the

The fallback content to display on prerendering

authentication is valid.

If the Challenge is a success and is valid, it will contains a code to retrieve the authentication

The fallback content to display on prerendering

. This

The fallback content to display on prerendering

enables the

The fallback content to display on prerendering

to access the service or

The fallback content to display on prerendering

Conclusion

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

The fallback content to display on prerendering

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
The fallback content to display on prerendering
login to create a new account for your
The fallback content to display on prerendering
.
Magic Link challenge, a feature that enhances security while simplifying authentication.

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

Use authentication and authorization scenarios in a test environment to check that the process runs smoothly.
Take advantage of activity monitoring features to quickly identify and resolve any problems relating to authentication and user management.

If you'd like to go even further, we encourage you to explore our advanced features such as two-factor authentication (coming soon) to further enhance security.

Alternatives

If the

The fallback content to display on prerendering

prefers using their password, we offer an alternative: the password. Find out more about this authentication method in our password integration guide. So, even if the

The fallback content to display on prerendering

prefers using their password, they can still access the

The fallback content to display on prerendering

securely and conveniently.
To offer your users a convenient and secure login experience, we offer one more alternative authentication methods: Single Sign-On (SSO). To benefit from these features, the

The fallback content to display on prerendering

must support these specific authentication methods.

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
POST /api/v2/org/:org_domain/magic-link-connection
Create a magic link connection
POST /api/v2/magic-link-challenge
Create a magic link challenge

Magic Link

1 Configure your first Magic Link 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​

Magic Link Connection creation​

Update the Magic Link Connection​

Delete the Magic Link Connection​

Retrieve the Magic Link Connection​

2 Integrate the Magic Link authentication to your Application​

Login​

Challenge a Magic Link​

Magic Link Challenge with Org Domain​

Full example of processing of results​

Conclusion​

Alternatives​

API endpoint used in this guide​

1 Configure your first Magic Link 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

Magic Link Connection creation

Update the Magic Link Connection

Delete the Magic Link Connection

Retrieve the Magic Link Connection

2 Integrate the Magic Link authentication to your Application

Login

Challenge a Magic Link

Magic Link Challenge with Org Domain

Full example of processing of results

Conclusion

Alternatives

API endpoint used in this guide