> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rownd.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a magic link

> Generate a magic link



## OpenAPI

````yaml POST /hub/auth/magic
openapi: 3.1.0
info:
  title: Rownd API
  version: 1.0.0
servers:
  - url: https://api.rownd.io
    description: Rownd production environment
  - url: https://api.us-east-2.dev.rownd.io
    description: Rownd development environment
security:
  - hubAccessTokenForRowndApi: []
tags:
  - name: applications
  - name: application_creds
  - name: application_schemas
paths:
  /hub/auth/magic:
    post:
      description: Generate a magic link
      operationId: hub_auth_magic_create
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                purpose:
                  type: string
                  enum:
                    - auth
                    - shorten
                  description: >
                    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.
                redirect_url:
                  type: string
                  description: >
                    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:
                  type: string
                  description: >-
                    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
                  pattern: >-
                    ^(\d+|\d+\.\d+)
                    ?(seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)$
                link_data:
                  type: object
                  additionalProperties: true
                  description: >
                    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:
                  type: string
                  enum:
                    - email
                    - phone
                  description: >
                    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.
                data:
                  type: object
                  additionalProperties: true
                  description: >
                    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:
                  type: string
                  description: >
                    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.
                  default: __default__
                group_to_join:
                  type: string
                  description: >
                    The ID of a group which the user will auto-join upon
                    completing sign-in. The group

                    must have an `'open'` admission policy.
      responses:
        '200':
          description: Successfully created magic link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MagicLinkCreateResponse'
      security:
        - appKey: []
          appSecret: []
        - hubAccessTokenForRowndApi: []
components:
  schemas:
    MagicLinkCreateResponse:
      properties:
        link:
          type: string
          description: The magic link URL
          example: https://rownd.link/c8fLG0a
        app_user_id:
          type: string
          description: >
            The user ID specified during creation or the resolved user ID if one
            of the directives

            was specified (e.g. `'__default__'`)
          example: user_fmpsrdqfcqzyicf3msor42e8
  securitySchemes:
    hubAccessTokenForRowndApi:
      type: http
      scheme: bearer
      description: >
        Bearer authentication header of the form `Bearer <token>` where
        `<token>` is your Rownd JWT
    appKey:
      type: apiKey
      in: header
      name: x-rownd-app-key
      description: >-
        The publishable key of your application credentials. ([more
        details](/configuration/app-credentials#appkey))
    appSecret:
      type: apiKey
      in: header
      name: x-rownd-app-secret
      description: >-
        The private secret of your application credentials. ([more
        details](/configuration/app-credentials#appsecret))

````