Redirect login links

Redirect login links as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Send an embedded identity into hosted Signal with a short-lived, one-time URL.

Redirect login links open the hosted Signal application in a top-level browser navigation. They are separate from iframe embed sessions and cannot be used as embed-session tokens.

Hosted rolesThe identity’s grant controls authorization after sign-in. viewer is read-only, editor manages supported operational features, and admin additionally manages settings within the granted project or location. A login link authenticates the identity and never elevates its role.

Server-side onlyCreate, inspect, and revoke login links from your backend with a Signal API key. Never expose an API key in browser code, logs, or a public URL. Treat each returned login URL as a temporary credential.

Direct embedded authenticationThe supplied external_user_id resolves an embedded identity in the API key’s workspace. Redemption creates a hosted Platform session directly for that identity. Signal does not create a normal Ceyo user, mirror its grants, or match an existing account by email.

Access and destination checksThe API key needs login_links:manage, and the requested project or location package must be active. The workspace must also have hosted white-label enabled. Signal verifies the API key, package, identity, and grant both when the link is created and when it is used. Return URLs must use an exact HTTPS origin in the API key’s allowed_origins; redirect paths stay within hosted Signal.

POST

/login-links

Creates a one-time hosted Signal login URL for an embedded identity and a project or location it can access.

Request

Request body

external_user_idstring

Required external identifier of the embedded identity that will sign in directly. Maximum: 200 characters.

project_idproject UUID | project external ID

Required project identifier. The embedded identity must already have access to this project.

location_idlocation UUID | location external ID | null

Optional location within the project. When supplied, the embedded identity must have access to this location.

landingauto | projects | locations | null

Optional simple landing choice. auto applies resource-count routing, projects opens the Projects list, and locations opens the selected project’s Locations list. Cannot be combined with location_id or redirect_path.

redirect_pathstring | null

Optional relative path to open in hosted Signal after sign-in. Must begin with one slash and cannot contain a scheme, host, backslash, or protocol-relative URL. Defaults to the selected project or location home.

return_urlhttps URL | null

Optional URL shown as the safe return destination from Signal. It overrides the workspace default return URL. Its origin must be registered for the API key; fragments and embedded credentials are rejected.

expires_ininteger

Optional lifetime in seconds. Defaults to 900 (15 minutes); minimum: 60; maximum: 3,600 (1 hour).

Safe navigationOmit both destination fields to open the selected project or location overview. Use landing: "auto", landing: "projects", or landing: "locations" for common destinations. Use redirect_path for an advanced internal page; it cannot be combined with landing. return_url controls where the user may return afterward and overrides the workspace default. Signal does not accept arbitrary origins, JavaScript URLs, protocol-relative URLs, path traversal, or URLs containing credentials. After sign-in, hosted Signal displays the workspace-configured return action when either a validated return_url or a workspace default return URL is available.

Response

Response envelope

login_link:LoginLink

The requested or resulting login link.

Object

LoginLink

iduuid

Stable login link identifier used for lifecycle requests.

urlstring | null

Hosted Signal sign-in URL. Returned only when the link is created; lifecycle responses return null.

statuspending | used | expired | revoked

Current one-time login link status.

expires_atdatetime

Time the pending link expires, in ISO 8601 format.

used_atdatetime | null

Time the link was successfully used, or null if it was not used.

created_atdatetime

Time the link was created, in ISO 8601 format.

Request and response

curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/login-links' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "external_user_id": "customer-user-4821",
  "project_id": "partner-project-acme",
  "location_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
  "redirect_path": "/workspaces/{workspace_id}/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58/visibility",
  "return_url": "https://portal.partner.example/customers/4821",
  "expires_in": 900
}'

HTTP/1.1 201 Created

{
  "login_link": {
    "id": "7a73ed11-d5dc-4b6a-8681-d9e571d2a991",
    "url": "https://signal.ceyo.ai/login-links/7a73ed11-d5dc-4b6a-8681-d9e571d2a991?token=ceyo_login_...",
    "status": "pending",
    "expires_at": "2026-07-31T10:15:00Z",
    "used_at": null,
    "created_at": "2026-07-31T10:00:00Z"
  }
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}

Errors

Status codes

400invalid_request

The JSON body was not provided, is malformed, or contains an unknown field.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden | white_label_not_enabled | package_not_active

The API key lacks login_links:manage, the embedded identity lacks an active grant to the requested scope, hosted white-label is disabled for the workspace, or the assigned package is not active.

404not_found

The embedded identity, project, or location was not found for this API key.

422validation_failed

An identifier, expiry, redirect path, or return URL does not meet the documented constraints.

429rate_limit_exceeded

Too many login links were created or too many requests were made.

GET

/login-links/{login_link_id}

Returns the current state of a login link without changing it.

Parameters

Path parameters

login_link_iduuid

Required

Response

Response envelope

login_link:LoginLink

The requested or resulting login link.

Object

LoginLink

iduuid

Stable login link identifier used for lifecycle requests.

urlstring | null

Hosted Signal sign-in URL. Returned only when the link is created; lifecycle responses return null.

statuspending | used | expired | revoked

Current one-time login link status.

expires_atdatetime

Time the pending link expires, in ISO 8601 format.

used_atdatetime | null

Time the link was successfully used, or null if it was not used.

created_atdatetime

Time the link was created, in ISO 8601 format.

Read-only statusThis request returns pending, used, expired, or revoked and never changes the link. Used, expired, and revoked are terminal states. A terminal link cannot be used, revoked, or reactivated.

Request and response

curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/login-links/7a73ed11-d5dc-4b6a-8681-d9e571d2a991' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "login_link": {
    "id": "7a73ed11-d5dc-4b6a-8681-d9e571d2a991",
    "url": null,
    "status": "pending",
    "expires_at": "2026-07-31T10:15:00Z",
    "used_at": null,
    "created_at": "2026-07-31T10:00:00Z"
  }
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}

Errors

Status codes

400invalid_request

The login_link_id is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot manage login links.

404not_found

The login link was not found for this API key.

429rate_limit_exceeded

Too many requests were made.

DELETE

/login-links/{login_link_id}

Revokes a pending login link and returns its terminal revoked state.

Parameters

Path parameters

login_link_iduuid

Required

Response

Response envelope

login_link:LoginLink

The requested or resulting login link.

Object

LoginLink

iduuid

Stable login link identifier used for lifecycle requests.

urlstring | null

Hosted Signal sign-in URL. Returned only when the link is created; lifecycle responses return null.

statuspending | used | expired | revoked

Current one-time login link status.

expires_atdatetime

Time the pending link expires, in ISO 8601 format.

used_atdatetime | null

Time the link was successfully used, or null if it was not used.

created_atdatetime

Time the link was created, in ISO 8601 format.

Terminal-state behaviorA pending link changes to revoked and returns 200 OK. Used, expired, and revoked links remain unchanged and return 409 login_link_not_pending. Revoked links cannot be used or reactivated.

Request and response

curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/login-links/7a73ed11-d5dc-4b6a-8681-d9e571d2a991' \
  --header 'Authorization: Bearer ceyo_platform_...'

{
  "login_link": {
    "id": "7a73ed11-d5dc-4b6a-8681-d9e571d2a991",
    "url": null,
    "status": "revoked",
    "expires_at": "2026-07-31T10:15:00Z",
    "used_at": null,
    "created_at": "2026-07-31T10:00:00Z"
  }
}

ErrorsResponse format and status codes

Errors

Error response envelope

errorError

Structured error payload.

Errors

Error

codestring

Stable snake_case code suitable for programmatic handling.

messagestring

Human-readable explanation of the failure.

detailsobject | array | null

Structured validation or request context when available.

request_idstring

Identifier to provide when requesting support.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}

Errors

Status codes

400invalid_request

The login_link_id is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot manage login links.

404not_found

The login link was not found for this API key.

409login_link_not_pending

The link is used, expired, or revoked and remains in that terminal state.

429rate_limit_exceeded

Too many requests were made.