Request Parameters Response Elements Errors Examples See Also

CreateOneTimeDeepLinkCode

Generates a one-time code for deep-link authentication.

Direct the user's browser to the returned deepLinkUrl before it expires. The code is exchanged for an authenticated, domain-scoped session and can be used only once.

Request Parameters

domainId

The ID of the domain to generate the code for.

Type: String

Pattern: d-[0-9a-z]{1,25}

Required: Yes

redirectUrl

The URL to redirect to after the deep-link code is used. Must be an HTTPS URL in the domain with a path of /auth/callback, and cannot include a query string or fragment. If omitted, no redirect is applied.

Type: String

Required: No

ttlSeconds

How long the code remains valid, in seconds. Defaults to 300.

Type: Integer

Valid Range: Minimum value of 60. Maximum value of 600.

Required: No

Response Elements

The following elements are returned by the service.

code

The one-time deep-link code.

Type: String

deepLinkUrl

The deep-link URL containing the one-time code.

Type: String

expiresAt

The timestamp when the code expires.

Type: Timestamp

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

The caller is not authorized to perform this action.

HTTP Status Code: 403

InternalServerException

An unexpected error occurred while processing the request.

errorCode: The error code associated with the internal error.

HTTP Status Code: 500

ResourceNotFoundException

The specified resource does not exist.

errorCode: The error code associated with the failure.
resourceId: The identifier of the resource that could not be found. Not always present.
resourceType: The type of the resource that could not be found. Not always present.

HTTP Status Code: 404

ThrottlingException

The request was throttled due to exceeding the allowed request rate.

retryAfterSeconds: The number of seconds to wait before retrying the request. Not always present.

HTTP Status Code: 429

ValidationException

A parameter is specified incorrectly.

errorCode: The error code associated with the validation failure.

HTTP Status Code: 400

Examples

Create a one-time deep-link code

The following example creates a one-time deep-link code for a domain that remains valid for 300 seconds and, once used, redirects the browser to the domain's /auth/callback path. Direct the user's browser to the returned deepLinkUrl before it expires; the code can be used only once. Payloads are shown as JSON; on the wire they are CBOR-encoded.

Sample Request


{
  "domainId": "d-1a2b3c4d5e",
  "redirectUrl": "https://d-1a2b3c4d5e.cloudwatch-omni.global.app.aws/auth/callback",
  "ttlSeconds": 300
}

Sample Response


{
  "code": "dlc-EXAMPLE1234567890",
  "deepLinkUrl": "https://d-1a2b3c4d5e.cloudwatch-omni.global.app.aws/deeplink?code=EXAMPLE1234567890",
  "expiresAt": "2026-09-16T14:27:31Z"
}