API docs by Redocly

DyLy Link API (v1)

Download OpenAPI specification:

DyLy Link API

create links

Creates a DyLy short link belonging to the authenticated project.

Supported link types

  • url: Redirects the visitor to destinationUrl.
  • json: Returns the JSON payload stored in rawJson.
  • jwt: Returns a signed JWT built from jwtClaims. When destinationUrl is supplied the JWT is delivered via the redirect target; otherwise it is returned inline. Implicit flow appends the token to the fragment, while code flow issues a one-time authorization code.
  • deep: Issues a deep link with a signed token query string for downstream validation. If the app is not installed the user is redirected to destinationUrl.

Validation and defaults

  • projectId must belong to the caller. Authorization failures return 401 or 403.
  • domain is normalized to lowercase and must be registered for the project. When omitted the project's default domain is used.
  • TTL (expiresIn) defaults to unlimited access when capabilities allow. If the project cannot control TTL, the service forces a 24 hour TTL. A positive TTL must be at least 60 seconds.
  • For jwt links jwtClaims are required. Providing a destinationUrl also requires flow; setting flow: code additionally requires clientType. A secure code verifier is generated automatically for code flow.
  • For json links rawJson must contain a valid payload within platform limits (depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters).
  • For url and deep links destinationUrl must be an absolute http(s) URL.
  • oneTime and keyProtected require the corresponding project capability. If the project lacks the capability the value is coerced to false. When keyProtected is enabled the returned shortUrl contains a key query string parameter.
  • Custom path values must match the documented pattern. When omitted a unique path is generated.

Response

  • Returns the persisted link metadata including the generated alias and, for JWT code flow, the server-issued codeVerifier.

Rate limiting & quotas

  • Project rate limits and link quotas are evaluated for every request. Exceeding the limits results in 429 or 403 responses depending on the violation.
header Parameters
Authorization
required
string non-empty
Example: Basic YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo6MTIzNDU2Nzg5MA==

HTTP Basic authentication using the DyLy client credentials. Format: Authorization: Basic base64(clientId:clientSecret) for a client that can access the target project.

Request Body schema: application/json
required
projectId
required
string <uuid> = 36 characters

GUID of the project that owns the link. Must match the authenticated project context and must be a valid UUID v4 format.

type
required
string
Enum: "url" "json" "jwt" "deep"

Link type to create. Supported values: url, json, jwt, or deep. Each type drives validation and how the link behaves when accessed.

domain
string [ 1 .. 255 ] characters

Domain that will host the link (e.g., myproject.dyly.dev). Must be lowercase and registered to the project. If omitted, the project's default domain is used.

destinationUrl
string [ 1 .. 1024 ] characters

Absolute HTTP(S) URL to redirect to. Required for url and deep links, optional for jwt links. When provided for jwt, you must also set flow.

path
string [ 1 .. 110 ] characters

Optional custom path (1–3 segments of lowercase letters, digits, -, or .). Each segment can be 1-36 characters. The service generates a unique path when omitted. Reserved paths such as .well-known/jwks.json, state-validation, and deferred-params are rejected.

rawJson
object

JSON payload returned when the link is accessed. Required for json links. Payloads must satisfy platform limits (nesting depth ≤ 4, arrays ≤ 10 items, string length ≤ 192 characters).

jwtClaims
object

Claims to include in JWT responses. Required for jwt links and optional for deep links. Reserved top-level claims (iss, iat, exp, nbf, jti, path, queryString, fragment) are populated by the service and must not be supplied.

jwtExpiresIn
number [ 300 .. 86400 ]

Lifetime of the issued JWT in seconds. Accepts values between 300 (5 minutes) and 86,400 (24 hours). Defaults to 900 (15 minutes).

expiresIn
number [ 0 .. 31536000 ]

Lifetime of the link in seconds. 0 (default) keeps the link active indefinitely when allowed. Positive values below 60 are rejected. If the project cannot manage TTL, the service coerces the value to 86,400 seconds (24 hours). Maximum is 31,536,000 seconds (1 year).

oneTime
boolean
Default: false

When true, the link can be used only once. Requires the one-time-link capability (Standard Plan); otherwise the value is forced to false.

keyProtected
boolean
Default: false

When true, the link requires an opaque key query parameter for access. Requires the protected-link capability (Standard Plan); otherwise the value is forced to false. If enabled, the response includes the generated key in shortUrl.

flow
string
Enum: "implicit" "code"

JWT retrieval flow when type is jwt and destinationUrl is specified. Use implicit to append the token to the URL fragment, or code to issue a one-time authorization code with PKCE support.

clientType
string
Enum: "public" "confidential"

Required when flow is code. Indicates whether the link was created for a public or confidential client, which controls PKCE requirements. Public clients must provide a code verifier, while confidential clients use a client secret.

Responses

Request samples

Content type
application/json
{
  • "projectId": "11111111-1111-1111-1111-111111111111",
  • "type": "json",
  • "domain": "myproject.dyly.dev",
  • "destinationUrl": "https://www.example.com",
  • "path": "my-custom-path",
  • "rawJson": { },
  • "jwtClaims": { },
  • "jwtExpiresIn": 900,
  • "expiresIn": 3600,
  • "oneTime": true,
  • "keyProtected": true,
  • "flow": "code",
  • "clientType": "confidential"
}

Response samples

Content type
application/json
{
  • "projectId": "11111111-1111-1111-1111-111111111111",
  • "destinationUrl": "https://www.example.com",
  • "path": "my-custom-path",
  • "rawJson": { },
  • "jwtClaims": { },
  • "shortUrl": "https://myproject.dyly.dev/my-custom-path",
  • "alias": "bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u",
  • "expiresIn": 3600,
  • "jwtExpiresIn": 900,
  • "createdAt": "2024-01-15T10:30:00Z",
  • "oneTime": true,
  • "type": "json",
  • "keyProtected": true,
  • "flow": "code",
  • "domain": "myproject.dyly.dev",
  • "codeVerifier": "generatedVerifier456",
  • "clientType": "confidential"
}

list links

Retrieves paginated short links for the specified domain within the authenticated project.

  • domain must belong to the project.
  • maxItemCount defaults to 100 items and higher values are clipped to that maximum.
  • continuationToken should be the string value returned by the previous page. Omit it to receive the first page.
query Parameters
domain
required
string [ 1 .. 255 ] characters
Example: domain=myproject.dyly.dev

Fully qualified domain name that owns the links to return (e.g., myproject.dyly.dev). Must be registered to the authenticated project. The domain is normalized to lowercase.

maxItemCount
integer [ 1 .. 100 ]
Default: 100
Example: maxItemCount=50

Maximum number of links to return per page. Defaults to 100 and must be between 1 and 100. Values above 100 are coerced to 100.

continuationToken
string <= 256 characters

Opaque continuation token returned by a previous list-short-urls response. Use this to retrieve the next page of results. Omit this parameter to retrieve the first page.

header Parameters
Authorization
required
string non-empty
Example: Basic YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo6MTIzNDU2Nzg5MA==

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client that can read links for the supplied domain.

Responses

Response samples

Content type
application/json
{
  • "projectId": "11111111-1111-1111-1111-111111111111",
  • "continuationToken": "token123abc",
  • "links": [
    ]
}

delete link

Permanently deletes a short link and any stored sessions tied to the alias. The operation is idempotent for authorized callers.

  • The alias is the string returned when the link was created.
  • Deleting a link prevents future redirects.
path Parameters
alias
required
string [ 1 .. 1024 ] characters
Example: bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u

The unique identifier (alias) of the link to delete. This is the base64-encoded value returned when the link was created. Accepts alphanumeric characters, hyphens, underscores, and equals signs.

header Parameters
Authorization
required
string non-empty
Example: Basic YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo6MTIzNDU2Nzg5MA==

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client authorized to delete links in the target project.

Responses

Response samples

Content type
application/json
{
  • "errorCode": "INVALID_PARAMETER",
  • "errorMessage": "The provided alias does not match the required format",
  • "correlationId": "33333333-3333-3333-3333-333333333333"
}

get link

Retrieves the latest metadata for a short link identified by its alias. Use this endpoint to confirm TTL, key protection, client type, and generated code verifier values.

  • The alias is the string value returned during creation.
  • Successful responses include the same shape as link creation.
path Parameters
alias
required
string [ 1 .. 1024 ] characters
Example: bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u

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

header Parameters
Authorization
required
string non-empty
Example: Basic YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo6MTIzNDU2Nzg5MA==

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client permitted to read link details for the project.

Responses

Response samples

Content type
application/json
{
  • "projectId": "11111111-1111-1111-1111-111111111111",
  • "destinationUrl": "https://www.example.com",
  • "path": "my-custom-path",
  • "rawJson": { },
  • "jwtClaims": { },
  • "shortUrl": "https://myproject.dyly.dev/my-custom-path",
  • "alias": "bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u",
  • "expiresIn": 3600,
  • "jwtExpiresIn": 900,
  • "createdAt": "2024-01-15T10:30:00Z",
  • "oneTime": true,
  • "type": "json",
  • "keyProtected": true,
  • "flow": "code",
  • "domain": "myproject.dyly.dev",
  • "codeVerifier": "generatedVerifier456",
  • "clientType": "confidential"
}

update link

Updates mutable properties of an existing short link identified by its alias.

Updatable properties:

  • destinationUrl: Can only be changed if originally specified. Cannot be added if the link was created without it, and cannot be removed once set.
  • rawJson: Only for links of type: json. Updates the JSON payload returned when the link is accessed.
  • jwtClaims: Only for links of type: jwt. Updates the JWT claims used to generate tokens.
  • jwtExpiresIn: Only for links of type: jwt. Updates the JWT token expiration time (in seconds).
  • expiresIn: Updates the link's time-to-live. If the project lacks the LinkTtl capability, this value may be ignored or coerced to a default of 24 hours. Positive values must be at least 60 seconds.

Immutable properties: The following properties cannot be changed after creation: projectId, domain, path, alias, type, oneTime, keyProtected, flow, clientType.

Validation:

  • The alias must belong to a link in the authenticated project.
  • Property updates must be consistent with the link's type (e.g., rawJson can only update json links).
  • A request with no valid updates returns a success response without changing the link.

Response: Returns the updated link metadata in the same format as link creation and retrieval.

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

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

header Parameters
Authorization
required
string non-empty
Example: Basic YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo6MTIzNDU2Nzg5MA==

HTTP Basic credentials (Basic base64(clientId:clientSecret)) for a client authorized to update links in the target project.

Request Body schema: application/json
required
destinationUrl
string <uri> [ 1 .. 1024 ] characters

The destination URL to redirect users to. Can only be updated if the link was originally created with a destinationUrl. Cannot be added if not originally present, and cannot be removed once set. Must be a valid absolute http(s) URL.

rawJson
object

JSON payload returned when accessing the link. Only for links with type: json. Must satisfy the same validation rules as during creation (max depth 4, max array length 10, max string length 192 characters).

jwtClaims
object

JWT claims to include in generated tokens. Only for links with type: jwt. The same reserved keys (iss, iat, exp, nbf, jti, path, queryString, fragment) apply and will be automatically managed by the service.

jwtExpiresIn
integer [ 300 .. 86400 ]

JWT token expiration time in seconds. Only for links with type: jwt. Must be between 300 (5 minutes) and 86400 (24 hours).

expiresIn
integer [ 0 .. 31536000 ]

Link time-to-live in seconds. Zero indicates unlimited (if project capabilities allow). Positive values must be at least 60 seconds. Maximum is 31536000 (1 year). Projects without the LinkTtl capability may have this value coerced to 24 hours.

Responses

Request samples

Content type
application/json
{
  • "destinationUrl": "https://www.example.com/updated-path",
  • "rawJson": {
    },
  • "jwtClaims": {
    },
  • "jwtExpiresIn": 1800,
  • "expiresIn": 7200
}

Response samples

Content type
application/json
{
  • "projectId": "11111111-1111-1111-1111-111111111111",
  • "destinationUrl": "https://www.example.com",
  • "path": "my-custom-path",
  • "rawJson": { },
  • "jwtClaims": { },
  • "shortUrl": "https://myproject.dyly.dev/my-custom-path",
  • "alias": "bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u",
  • "expiresIn": 3600,
  • "jwtExpiresIn": 900,
  • "createdAt": "2024-01-15T10:30:00Z",
  • "oneTime": true,
  • "type": "json",
  • "keyProtected": true,
  • "flow": "code",
  • "domain": "myproject.dyly.dev",
  • "codeVerifier": "generatedVerifier456",
  • "clientType": "confidential"
}

get JWT

Exchanges a one-time authorization code for a signed JWT issued for the specified short link alias.

  • Accepts both confidential and public clients. Confidential clients must supply clientSecret; public clients must provide the codeVerifier that was generated during link creation.
  • The code value is single-use and expires shortly after issuance. Requests with an incorrect code, mismatched alias, or mismatched client type return 400.
  • The endpoint validates stored PKCE data when available.
  • Successful responses return the JWT and a derived JWKS URI.
path Parameters
alias
required
string [ 1 .. 1024 ] characters
Example: bXlwcmlqZWN0LmR5bHkuYXBwIy53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9u

The unique identifier (alias) of the JWT-protected link. This is the base64-encoded value associated with the authorization code.

Request Body schema: application/x-www-form-urlencoded
required
code
required
string = 32 characters

One-time authorization code to exchange for a JWT. Codes are exactly 32 characters, expire shortly after issuance, and can only be used once.

clientId
required
string <uuid> = 36 characters

Client application identifier (UUID v4). Must correspond to the client configured for the link and be a valid UUID format.

clientType
required
string
Enum: "public" "confidential"

Classification of the client making the request. Accepts confidential or public and must match the link configuration.

clientSecret
string [ 64 .. 96 ] characters

Required when clientType is confidential. Provide the stored client secret value issued by DyLy. Length: 64-96 characters.

codeVerifier
string [ 1 .. 256 ] characters

PKCE code verifier tied to the authorization code. Mandatory for public clients and optional for confidential clients. Length: 1-256 characters.

Responses

Response samples

Content type
application/json
{}