API Referenceshort-url

DyLy Link Utility API

DyLy link utility API

Version
v1
Server
https://<your link domain>

links

get/state-validation

state validation

#state-validation

Validates the CSRF state token and cookie to ensure the authorization flow has not been tampered with. This endpoint is called after a redirect from an OAuth-style authorization flow to verify that the state matches the session cookie.

Purpose

  • Prevents CSRF attacks in OAuth-like flows
  • Verifies that the client initiating the flow is the same as the one completing it
  • Returns session metadata including click timestamp, user agent, and IP address

Flow

  1. Client initiates link access and receives a state parameter
  2. After redirect, client calls this endpoint with the state, clientId, and alias
  3. Server validates the state matches the stored session cookie
  4. Returns validation result with session information

Usage

  • Typically called by client applications implementing OAuth code flow
  • Used with JWT links that have flow: code configuration

Parameters

statequeryrequired

CSRF protection token (UUID v4 format) that was issued when the link was first accessed. This value must match the session cookie to prevent CSRF attacks.

string / uuid

clientIdqueryrequired

Client application identifier (UUID v4) that is requesting validation. Must match the clientId associated with the link.

string / uuid

aliasqueryrequired

The unique identifier (alias) of the link being validated. This is the base64-encoded value returned when the link was created.

string

Responses

200application/json

State validation completed. Returns the validation result and session metadata.

object

  • cookieValidationrequiredstring

    The result of the cookie validation. Returns VALID if the state token matches the session cookie, indicating the request came from the same browser session that initiated the flow. Returns INVALID if there is a mismatch, which may indicate a CSRF attack or expired session.

  • clickedAtrequiredstring / date-time

    ISO 8601 timestamp indicating when the link was originally clicked. This helps track the elapsed time between the initial click and the validation request.

  • userAgentrequiredstring

    The User-Agent string from the browser that originally clicked the link. This information can be used for analytics, device fingerprinting, or detecting potential fraud.

  • ipAddressrequiredstring / ipv4

    The IP address from which the link was originally clicked. This can be used for geolocation, fraud detection, or comparing with the current request's IP address.

400application/json

Invalid request. One or more parameters do not match the required format or validation failed.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

401application/json

Unauthorized. The state token does not match the session cookie or has expired.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Not found. The specified alias or session does not exist.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

get/deferred-params

Get deep link deferred parameters

#get-deferred-parameters

Retrieves deferred deep link parameters when a mobile app is installed for the first time. This endpoint enables seamless app onboarding by allowing the app to retrieve the deep link context that triggered the installation.

Use case

  1. User clicks a deep link but the app is not installed
  2. User is redirected to the app store to install the app
  3. After installation, the app calls this endpoint to retrieve the original deep link parameters
  4. App processes the parameters and takes the user to the intended destination

Matching algorithm

  • Server attempts to match the requesting device with a recent click session
  • Uses device fingerprinting (user agent, IP address, etc.)
  • Returns a matching score (0.0 to 1.0) indicating confidence level
  • Higher scores indicate better device matches

Token contents

  • The returned JWT token contains the deep link parameters and claims
  • Token is signed and can be validated using the JWKS endpoint
  • Includes timestamp and session metadata

Best practices

  • Call this endpoint soon after app installation for best matching results
  • Check the matching score before processing the parameters
  • Handle cases where no match is found (score is very low or token is empty)

Parameters

clientIdqueryrequired

Client application identifier (UUID v4) for the mobile app requesting deferred parameters. Must match a clientId configured in the system.

string / uuid

Responses

200application/json

Deferred parameters retrieved successfully. Returns a JWT token containing the deep link parameters and a matching score.

object

  • tokenrequiredstring

    Signed JWT token containing the deferred deep link parameters and claims. The token payload includes the original link parameters, timestamp, and session metadata. Validate this token using the JWKS endpoint (.well-known/jwks.json) before processing. Empty string if no matching session was found.

  • matchingScorerequirednumber / double

    Confidence score (0.0 to 1.0) indicating how well the current device/session matches the original click session. Higher scores (e.g., > 0.7) suggest a strong match based on device fingerprinting (user agent, IP address, timing). Lower scores may indicate uncertainty or that the app was installed on a different device. A score of 0.0 typically means no match was found.

400application/json

Invalid request. The clientId parameter does not match the required UUID format.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

404application/json

Not found. No matching deep link session found for this client or device fingerprint.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.

500application/json

Internal server error. An unexpected error occurred while processing the request.

object

  • errorCoderequiredstring

    A stable, machine-readable error code that identifies the specific type of error. Use this for programmatic error handling.

  • errorMessagerequiredstring

    A human-readable message that describes the error. This message may contain additional context about what went wrong and how to fix it.

  • correlationIdrequiredstring / uuid

    A unique identifier (UUID) for this request that can be used to trace the error in server logs. Include this ID when contacting support. This value matches the X-Correlation-Id response header.