POST
/
hub
/
auth
/
magic
curl --request POST \
  --url https://api.rownd.io/hub/auth/magic \
  --header 'Content-Type: application/json' \
  --header 'x-rownd-app-key: <api-key>' \
  --header 'x-rownd-app-secret: <api-key>' \
  --data '{
  "purpose": "auth",
  "redirect_url": "/somewhere/in/my/app#",
  "expiration": "30d",
  "link_data": {},
  "verification_type": "email",
  "data": {
    "email": "gary@foo.com",
    "first_name": "Gary"
  },
  "user_id": "__default__",
  "group_to_join": "<string>"
}'
{
  "link": "https://rownd.link/c8fLG0a",
  "app_user_id": "user_fmpsrdqfcqzyicf3msor42e8"
}

Authorizations

​
x-rownd-app-key
string
header
required

The publishable key of your application credentials. (more details)

​
x-rownd-app-secret
string
header
required

The private secret of your application credentials. (more details)

Body

application/json
​
purpose
enum<string>

Determines whether this link will identify a user and allow them to sign in automatically or whether it will just act as a simple redirect. An auth link should only be sent to a single user, whereas a shorten link can be sent to many users if desired, since it does not carry an authentication payload.

Available options:
auth,
shorten
​
redirect_url
string

The absolute URL or relative path to send your user after sign-in. If the URL is relative, it will be appended to your application's default redirect URL as defined in your Rownd application settings. If no default redirect is set, the magic link creation will fail.

Example:

"/somewhere/in/my/app#"

​
expiration
string

A human-readable string representing the duration for which a magic link is valid. Examples of valid values include 1h, 2d, 3w, 1m, etc. May not exceed 30d. Defaults to 30d.

Example:

"30d"

​
link_data
object

A dictionary of key-value pairs to store with the magic link. These values will be returned in the magic link response and can be used to store any additional data you need to associate with the link.

Do not store sensitive data in this field, as it can be read by anyone who has the link. Fetching the link with Accept: application/json will return the redirect link along with the link_meta field. In mobile SDKs, this is returned to you as part of the payload to your magic link delegate/callback.

​
verification_type
enum<string>

The means by which this magic link will be verified by the user. When the magic link is visited, the user's email or phone number will be marked as verified depending on verification mode. In practice, you should set this value to 'phone' if you are sending this link to the user via SMS. Likewise, set to 'email' if you are sending the magic link to the user via email.

Available options:
email,
phone
​
data
object

Data to add to the user's profile. These properties must exist in the Profile Data portion of the Rownd application. If properties such as email, phone, etc identify an existing user, the user will be auto-matched regardless of the user_id value.

Example:
{
  "email": "gary@foo.com",
  "first_name": "Gary"
}
​
user_id
string
default:__default__

Specify a user ID. If the user already exists, include their user ID. Otherwise, use one of '__default__', '__uuid__', or '__objectid__'. These special values tell Rownd to generate an ID in the provided format, or use the application's default user ID format.

​
group_to_join
string

The ID of a group which the user will auto-join upon completing sign-in. The group must have an 'open' admission policy.

Response

200 - application/json
Successfully created magic link
​
link
string

The magic link URL

Example:

"https://rownd.link/c8fLG0a"

​
app_user_id
string

The user ID specified during creation or the resolved user ID if one of the directives was specified (e.g. '__default__')

Example:

"user_fmpsrdqfcqzyicf3msor42e8"