Customer access

Customer access as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Give each customer the correct project or location scope through an embedded Signal application or a short-lived link to hosted Signal.

Choose embedded or hosted access

Both access modes use an embedded identity and its project or location grants. Choose where the customer should work.

Embedded accessMount Signal inside your product with a short-lived embed session. Your backend mints the token, and the browser receives only that token. Embed roles are viewer or editor.

Hosted accessThe hosted Signal application follows the identity's normal role, grant, and feature permissions. To send a customer into it with a redirect login link, enable hosted white-label for the workspace and assign an active package to the resource.

Origin configurationFor embeds, add each HTTPS host-page origin to the issuing API key's allowed_origins. The same allowlist validates an optional hosted-login return_url.

Keep the API key server-sideCreate embed sessions and login links from your authenticated backend. Never place a Signal API key in browser code or loader options.

Provision identities and access grants

Use a workspace-scoped key with identities:manage. The external user ID is unique within the workspace, and repeating the request updates the same identity.

# Upsert an identity using your stable user ID.
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-42' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "user-42@example.com",
    "name": "User 42"
  }'

# Grant access to one project.
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-42/projects/customer-project/access' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{ "role": "viewer" }'

Project grantGrants project access. It also applies when issuing a location-scoped session beneath that project.

Location grantUse the nested /projects/{project_id}/locations/{location_id}/access path to restrict access to one location. To grant one to 100 locations in the same project without minting a session, POST /projects/{project_id}/locations/access with location_grants.

Granted-location portfolioMint with location_scope: "granted" and no location_id to expose active direct location grants in one project. Signal resolves them live, preserves each location's role, and ignores project grants for this scope. Revoking one grant removes only that location. The embed exposes Overview and Locations, not project-wide routes.

RolesGrants accept viewer, editor, or admin. Embed sessions expose only viewer or editor; an admin grant resolves to editor in the iframe.

LifecycleSet an identity to disabled to block new access and revoke its active embed sessions. Delete a grant to remove that resource scope.

Batch location grantsPOST /embedded-identities/{external_user_id}/projects/{project_id}/locations/access atomically ensures one to 100 direct location grants, including admin, without issuing a session. Use this for onboarding. POST /embed/sessions can still upsert an identity, create viewer or editor grants, and issue the first session through provision.location_grants. Inline provisioning requires a workspace-scoped key with both embed_sessions:create and identities:manage.

{
  "location_grants": [
    { "location_id": "store-amsterdam", "role": "editor" },
    { "location_id": "store-utrecht", "role": "viewer" }
  ]
}

{
  "external_user_id": "regional-manager-42",
  "project_id": "customer-project",
  "location_scope": "granted",
  "provision": {
    "location_grants": [
      { "location_id": "store-amsterdam", "role": "editor" },
      { "location_id": "store-utrecht", "role": "viewer" }
    ]
  }
}

Create redirect login links

Use a key with login_links:manage. The identity must be active and already have access to the requested project or location, the workspace must have hosted white-label enabled, and the assigned package must be active.

curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/login-links' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "external_user_id": "customer-user-42",
    "project_id": "customer-project",
    "expires_in": 900
  }'

Lifetimeexpires_in defaults to 900 seconds and accepts 60 to 3,600 seconds.

One-time useSend the returned login_link.url directly to the intended customer. Redemption marks it used, so it cannot be redeemed again.

DestinationOmit landing and redirect_path to open the selected project or location. Set landing to auto, projects, or locations for common landing pages. Use redirect_path alone for an advanced internal page.

Access checksSignal checks the API key, active package, identity, and grant when the link is issued and redeemed. A link authenticates the identity but does not add permissions or bypass feature access.

Return URLAn optional return_url must use HTTPS and an origin listed in the issuing API key's allowed_origins.

Inspect or revokeUse GET /login-links/{login_link_id} to inspect status. Use DELETE on the same path to revoke a link while it is still pending. Treat the returned URL as a secret.

Manage session renewal and revocation

Embed sessions default to 3,600 seconds and accept a TTL from 60 to 86,400 seconds. Refresh them through your backend; never expose the API key to the browser.

curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embed/sessions/refresh' \
  --header "Authorization: Bearer ${SIGNAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: ${UNIQUE_REQUEST_ID}" \
  --data '{
    "session_token": "${CURRENT_SESSION_TOKEN}",
    "ttl_seconds": 3600
  }'

Renew before expiryImplement the loader's onTokenExpired callback. Return the replacement token, or call embed.updateToken() after your backend refreshes it.

RotationA successful refresh exchanges the current token for a replacement. The exchanged token no longer authorizes embed API requests.

Access checksRefresh and embed requests recheck the identity, resource, grant, role, and issuing API key. If refresh is rejected, mint a new session only after your application confirms the user still has access.

Immediate revocationDisable the identity, revoke or change its grant, or revoke the issuing API key. Active embed requests then fail their live access check.

Use unique idempotency keysSession create and refresh requests require an Idempotency-Key. Reuse it only when retrying the same operation with the same request body.