Signal API
Embedded identities as MarkdownUse a clean Markdown version of this page with an agent or local tooling.

Embedded identities

Provision partner-managed identities for embedded experiences or redirect login, then assign project or location access by your stable external_user_id.

Embedded identities are controlled by your application. They do not receive invitations or use passwords. Mint embed sessions from your backend, or create redirect login links for hosted Signal, after provisioning the identity and its access.
Role behavior by access methodviewer and editor apply to both embedded and hosted access. admin enables project or location settings and partner-managed user administration after redirect login. Embed sessions never receive admin privileges; an admin grant is capped to editor in the embeddable.
Authentication and workspace scopeUse a workspace-scoped API key with identities:manage. Send it as Authorization: Bearer ceyo_platform_... on every request. The key selects the workspace, so paths do not include a workspace identifier. Keep the key on your server.
Stable external IDsChoose an immutable ID from your own system, not an email address. Matching is case-sensitive. URL-encode it in every resource path; for example, customer/user 42 becomes customer%2Fuser%2042.
GET
/embedded-identities

Returns embedded identities in the workspace selected by the API key, including their direct project and location grants.

Parameters

Query parameters

qstring

Case-insensitive search across external_user_id, email, and name.

Optional
statusactive | disabled

Return identities in one lifecycle status.

Optional
project_idproject UUID | project external ID

Return identities with direct access to this project or one of its locations.

Optional
location_idlocation UUID | location external ID

Return identities with direct access to this location. When location_id is an external ID, project_id is required.

Optional
roleviewer | editor | admin

Return identities with at least one matching direct project or location grant.

Optional
pageinteger

The 1-based page number.

OptionalDefault: 1
per_pageinteger

Number of identities per page. Minimum: 1; maximum: 100.

OptionalDefault: 25
Response

Response envelope

embedded_identities:EmbeddedIdentity[]pagination:Pagination
embedded_identitiesEmbeddedIdentity[]

Matching identities ordered by creation time newest first.

paginationPagination

Pagination metadata.

Object

EmbeddedIdentity

external_user_idstring

Stable, case-sensitive identifier supplied by your application.

emailstring | null

Optional contact or display email. It is profile data and is not used to sign in.

namestring | null

Optional display name.

avatar_urlstring | null

Optional absolute HTTPS URL for a display avatar.

metadataobject

Partner-defined JSON object. Values are returned as supplied and must not contain credentials or secrets.

statusactive | disabled

Active identities can receive access and use embed sessions or redirect login. Disabling an identity revokes active access sessions and pending login links.

project_accessProjectAccess[]

Direct project grants for the identity.

location_accessLocationAccess[]

Direct location grants for the identity.

created_atdatetime

Identity creation time in ISO 8601 format.

updated_atdatetime

Time the identity profile or status was most recently updated, in ISO 8601 format.

Object

ProjectAccess

project_iduuid

Ceyo UUID of the granted project.

roleviewer | editor | admin

Role granted across the project and all of its locations.

granted_atdatetime

Time the direct project grant was first created, in ISO 8601 format.

Object

LocationAccess

project_iduuid

Ceyo UUID of the project containing the location.

location_iduuid

Ceyo UUID of the granted location.

roleviewer | editor | admin

Role granted for this location.

granted_atdatetime

Time the direct location grant was first created, in ISO 8601 format.

Object

Pagination

pageinteger

Current 1-based page.

per_pageinteger

Number of identities requested per page.

totalinteger

Total identities matching the request.

total_pagesinteger

Total available pages.

Access filtersproject_id matches direct project grants and direct grants for locations in that project. location_id matches direct location grants only. Combine filters to narrow the same result set; an identity must satisfy every supplied filter.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities?q=avery&status=active&project_id=e6c96c98-d777-40e0-94ec-48931f57782f&role=viewer&page=1&per_page=25' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "embedded_identities": [
    {
      "external_user_id": "customer-user-4821",
      "email": "avery.quinn@example.com",
      "name": "Avery Quinn",
      "avatar_url": "https://cdn.example.com/avatars/customer-user-4821.png",
      "metadata": {
        "account_tier": "enterprise",
        "region": "emea"
      },
      "status": "active",
      "project_access": [
        {
          "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
          "role": "editor",
          "granted_at": "2026-07-31T09:30:00Z"
        }
      ],
      "location_access": [
        {
          "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
          "location_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
          "role": "viewer",
          "granted_at": "2026-07-31T09:35:00Z"
        }
      ],
      "created_at": "2026-07-31T09:20:00Z",
      "updated_at": "2026-07-31T09:35:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
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.

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

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

422validation_failed

One or more fields are invalid, the role is unsupported, or the location does not belong to the selected project.

429rate_limit_exceeded

Too many requests were made.

POST
/embedded-identities/{external_user_id}

Creates an embedded identity for external_user_id or updates the supplied profile fields on the existing identity.

Parameters

Path parameters

external_user_idstring

Your stable, case-sensitive identifier for the embedded identity. URL-encode the value before placing it in the path.

Required
Request

Request body

emailstring | null

Optional valid email address. Send null to clear it. The address is profile data only.

namestring | null

Optional display name, up to 200 characters. Send null to clear it.

avatar_urlstring | null

Optional absolute HTTPS avatar URL, up to 2,048 characters. Send null to clear it.

metadataobject

Optional partner-defined JSON object. When supplied, it replaces the complete metadata object; send {} to clear it.

statusactive | disabled

Optional lifecycle status. New identities default to active.

Idempotent upsertRepeating the same request produces the same identity state without creating a duplicate. New identities return 201 Created; existing identities return 200 OK. Omitted fields stay unchanged on an existing identity and use their documented defaults on creation. The path value cannot be changed.
Status changesSetting status to disabled preserves project and location grants while preventing new embedded sessions and revoking active embedded sessions. Set it back to active before minting another session.
Response

Response envelope

embedded_identity:EmbeddedIdentity

The requested or resulting embedded identity.

Object

EmbeddedIdentity

external_user_idstring

Stable, case-sensitive identifier supplied by your application.

emailstring | null

Optional contact or display email. It is profile data and is not used to sign in.

namestring | null

Optional display name.

avatar_urlstring | null

Optional absolute HTTPS URL for a display avatar.

metadataobject

Partner-defined JSON object. Values are returned as supplied and must not contain credentials or secrets.

statusactive | disabled

Active identities can receive access and use embed sessions or redirect login. Disabling an identity revokes active access sessions and pending login links.

project_accessProjectAccess[]

Direct project grants for the identity.

location_accessLocationAccess[]

Direct location grants for the identity.

created_atdatetime

Identity creation time in ISO 8601 format.

updated_atdatetime

Time the identity profile or status was most recently updated, in ISO 8601 format.

Object

ProjectAccess

project_iduuid

Ceyo UUID of the granted project.

roleviewer | editor | admin

Role granted across the project and all of its locations.

granted_atdatetime

Time the direct project grant was first created, in ISO 8601 format.

Object

LocationAccess

project_iduuid

Ceyo UUID of the project containing the location.

location_iduuid

Ceyo UUID of the granted location.

roleviewer | editor | admin

Role granted for this location.

granted_atdatetime

Time the direct location grant was first created, in ISO 8601 format.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "avery.quinn@example.com",
  "name": "Avery Quinn",
  "avatar_url": "https://cdn.example.com/avatars/customer-user-4821.png",
  "metadata": {
    "account_tier": "enterprise",
    "region": "emea"
  },
  "status": "active"
}'
Example responseJSON
HTTP/1.1 201 Created

{
  "embedded_identity": {
    "external_user_id": "customer-user-4821",
    "email": "avery.quinn@example.com",
    "name": "Avery Quinn",
    "avatar_url": "https://cdn.example.com/avatars/customer-user-4821.png",
    "metadata": {
      "account_tier": "enterprise",
      "region": "emea"
    },
    "status": "active",
    "project_access": [],
    "location_access": [],
    "created_at": "2026-07-31T09:20:00Z",
    "updated_at": "2026-07-31T09:20: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.

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

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

409conflict

The requested change conflicts with the current identity or resource state.

422validation_failed

One or more fields are invalid, the role is unsupported, or the location does not belong to the selected project.

429rate_limit_exceeded

Too many requests were made.

GET
/embedded-identities/{external_user_id}

Returns one embedded identity and all of its direct project and location grants.

Parameters

Path parameters

external_user_idstring

Your stable, case-sensitive identifier for the embedded identity. URL-encode the value before placing it in the path.

Required
Response

Response envelope

embedded_identity:EmbeddedIdentity

The requested or resulting embedded identity.

Object

EmbeddedIdentity

external_user_idstring

Stable, case-sensitive identifier supplied by your application.

emailstring | null

Optional contact or display email. It is profile data and is not used to sign in.

namestring | null

Optional display name.

avatar_urlstring | null

Optional absolute HTTPS URL for a display avatar.

metadataobject

Partner-defined JSON object. Values are returned as supplied and must not contain credentials or secrets.

statusactive | disabled

Active identities can receive access and use embed sessions or redirect login. Disabling an identity revokes active access sessions and pending login links.

project_accessProjectAccess[]

Direct project grants for the identity.

location_accessLocationAccess[]

Direct location grants for the identity.

created_atdatetime

Identity creation time in ISO 8601 format.

updated_atdatetime

Time the identity profile or status was most recently updated, in ISO 8601 format.

Object

ProjectAccess

project_iduuid

Ceyo UUID of the granted project.

roleviewer | editor | admin

Role granted across the project and all of its locations.

granted_atdatetime

Time the direct project grant was first created, in ISO 8601 format.

Object

LocationAccess

project_iduuid

Ceyo UUID of the project containing the location.

location_iduuid

Ceyo UUID of the granted location.

roleviewer | editor | admin

Role granted for this location.

granted_atdatetime

Time the direct location grant was first created, in ISO 8601 format.

Request and response

Example requestcURL
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
{
  "embedded_identity": {
    "external_user_id": "customer-user-4821",
    "email": "avery.quinn@example.com",
    "name": "Avery Quinn",
    "avatar_url": "https://cdn.example.com/avatars/customer-user-4821.png",
    "metadata": {
      "account_tier": "enterprise",
      "region": "emea"
    },
    "status": "active",
    "project_access": [
      {
        "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
        "role": "editor",
        "granted_at": "2026-07-31T09:30:00Z"
      }
    ],
    "location_access": [
      {
        "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
        "location_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
        "role": "viewer",
        "granted_at": "2026-07-31T09:35:00Z"
      }
    ],
    "created_at": "2026-07-31T09:20:00Z",
    "updated_at": "2026-07-31T09:35: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.

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

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404embedded_identity_not_found

No embedded identity has the supplied external_user_id in this workspace.

429rate_limit_exceeded

Too many requests were made.

DELETE
/embedded-identities/{external_user_id}

Permanently deletes an embedded identity and removes every direct project and location grant assigned to it.

Parameters

Path parameters

external_user_idstring

Your stable, case-sensitive identifier for the embedded identity. URL-encode the value before placing it in the path.

Required
Deletion effectsDeletion is synchronous and returns 204 No Content. Project and location resources are unchanged, but every access grant for this identity is removed. Active embedded sessions are revoked, and subsequent session creation or identity lookup fails until you upsert the external_user_id again.
Re-creating the identityUpserting the same external_user_id after deletion creates a new identity with no project or location access. Grant each required scope again before minting a session.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821' \
  --header 'Authorization: Bearer ceyo_platform_...'
Example responseJSON
HTTP/1.1 204 No Content
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.

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

Status codes

400invalid_request

A path value, query parameter, or JSON body is malformed.

401invalid_api_key

The Bearer API key is absent or invalid.

403forbidden

The API key cannot perform this operation.

404embedded_identity_not_found

No embedded identity has the supplied external_user_id in this workspace.

409conflict

The requested change conflicts with the current identity or resource state.

429rate_limit_exceeded

Too many requests were made.