API docs by Redocly

DyLy Link Utility API (v1)

Download OpenAPI specification:

DyLy link utility API

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
query Parameters
state
required
string <uuid> = 36 characters
Example: state=44444444-4444-4444-4444-444444444444

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.

clientId
required
string <uuid> = 36 characters
Example: clientId=22222222-2222-2222-2222-222222222222

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

alias
required
string [ 1 .. 1024 ] characters
Example: alias=bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u

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

Responses

Response samples

Content type
application/json
{
  • "cookieValidation": "VALID",
  • "clickedAt": "2024-01-15T10:30:00Z",
  • "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  • "ipAddress": "192.168.1.100"
}

Get deep link 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)
query Parameters
clientId
required
string <uuid> = 36 characters
Example: clientId=22222222-2222-2222-2222-222222222222

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

Responses

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV",
  • "matchingScore": 0.85
}