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

Access grants

Grant or revoke viewer, editor, or hosted admin access to projects and locations for an existing embedded identity.

Project grants apply across the project and all of its locations. Direct location grants apply only to the selected location. When both apply, the stronger role determines effective 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.
Grant identifiersexternal_user_id identifies an existing embedded identity and is case-sensitive. Project and location path values accept either Signal UUIDs or your configured external IDs.
Granted-location embed scopeCreate a session with location_scope: "granted" to expose the identity's active direct location grants in one project. This live scope preserves each location's role; adding, changing, or revoking a direct grant updates access, while a project grant never broadens it. Only Overview and Locations are available at project navigation level.
POST
/embedded-identities/{external_user_id}/projects/{project_id}/access

Creates or updates a direct project grant for an active embedded 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
project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID in the workspace selected by the API key.

Required
Request

Request body

roleviewer | editor | admin

Required role. viewer is read-only; editor permits supported operational changes; admin additionally manages hosted project or location settings and users.

Response

Response envelope

project_access:ProjectAccess

The requested or resulting direct project grant.

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.

Idempotent grantA new grant returns 201 Created. Repeating the request with the same role returns 200 OK, preserves granted_at, and makes no duplicate. Sending a different role updates the existing direct grant and also preserves granted_at.
Project scopeProject access applies to the project and all of its locations. Direct location grants may coexist with a project grant, but they do not reduce the effective project role.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821/projects/e6c96c98-d777-40e0-94ec-48931f57782f/access' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "role": "editor"
}'
Example responseJSON
HTTP/1.1 201 Created

{
  "project_access": {
    "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
    "role": "editor",
    "granted_at": "2026-07-31T09:30: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.

404resource_not_found

The embedded identity, project, or location was not found in this workspace.

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.

DELETE
/embedded-identities/{external_user_id}/projects/{project_id}/access

Removes the direct project grant for an embedded identity without deleting the identity or its direct 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
project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID in the workspace selected by the API key.

Required
Idempotent revokeThe endpoint returns 204 No Content whether the direct project grant existed or was already absent. The identity and project remain unchanged.
Remaining location accessRevoking project access does not remove direct location grants in the project. The identity can continue to reach those locations with their location roles. Revoke them separately when access to the entire project must end.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821/projects/e6c96c98-d777-40e0-94ec-48931f57782f/access' \
  --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.

404resource_not_found

The embedded identity, project, or location was not found in this workspace.

429rate_limit_exceeded

Too many requests were made.

POST
/embedded-identities/{external_user_id}/projects/{project_id}/locations/{location_id}/access

Creates or updates a direct grant to one location for an active embedded 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
project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID in the workspace selected by the API key.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the selected project.

Required
Request

Request body

roleviewer | editor | admin

Required role. viewer is read-only; editor permits supported operational changes; admin additionally manages hosted project or location settings and users.

Response

Response envelope

location_access:LocationAccess

The requested or resulting direct location grant.

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.

Idempotent grantA new grant returns 201 Created. Repeating the request with the same role returns 200 OK, preserves granted_at, and makes no duplicate. Sending a different role updates the existing direct grant and also preserves granted_at.
Location scopeThe grant applies only to the selected location. The location must belong to the project in the path. A direct project grant may provide broader or stronger effective access without changing this location grant.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58/access' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "role": "viewer"
}'
Example responseJSON
HTTP/1.1 201 Created

{
  "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"
  }
}
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.

404resource_not_found

The embedded identity, project, or location was not found in this workspace.

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.

POST
/embedded-identities/{external_user_id}/projects/{project_id}/locations/access

Creates or updates up to 100 direct location grants in one project for an active embedded identity, without issuing a session.

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
project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID in the workspace selected by the API key.

Required
Request

Request body

location_grantsLocationGrantInput[]

Required. One to 100 direct location grants in the selected project. Roles may differ between locations.

Request

LocationGrantInput

location_idlocation UUID | location external ID

Required location belonging to the selected project.

roleviewer | editor | admin

Required role. viewer is read-only; editor permits supported operational changes; admin additionally manages hosted project or location settings and users.

Response

Response envelope

location_access:LocationAccess[]

The requested or resulting direct location grants, in request order.

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.

Atomic batchThe request ensures the listed direct grants and returns 201 Created when at least one grant is new. When every listed grant already exists, it returns 200 OK. It does not add unlisted locations, remove existing grants, or issue an embed session. An invalid item rolls back the entire batch.
Idempotent grantRepeating the same request preserves each granted_at and makes no duplicate. Sending a different role updates that location grant and also preserves granted_at.
Location scopeEach grant applies only to its location. Every location must belong to the project in the path. A direct project grant may provide broader or stronger effective access without changing these location grants.

Request and response

Example requestcURL
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/access' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_grants": [
    {
      "location_id": "a1308d14-149c-4dd7-a4c5-295ac9090f58",
      "role": "viewer"
    },
    {
      "location_id": "b2419e25-250d-5ee8-b5d6-306bd0101f69",
      "role": "editor"
    }
  ]
}'
Example responseJSON
HTTP/1.1 201 Created

{
  "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"
    },
    {
      "project_id": "e6c96c98-d777-40e0-94ec-48931f57782f",
      "location_id": "b2419e25-250d-5ee8-b5d6-306bd0101f69",
      "role": "editor",
      "granted_at": "2026-07-31T09:36: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.

404resource_not_found

The embedded identity, project, or location was not found in this workspace.

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.

DELETE
/embedded-identities/{external_user_id}/projects/{project_id}/locations/{location_id}/access

Removes the direct location grant for an embedded identity without changing project access or grants to other locations.

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
project_idproject UUID | project external ID

Ceyo project UUID or configured partner external ID in the workspace selected by the API key.

Required
location_idlocation UUID | location external ID

Ceyo location UUID or configured partner external ID belonging to the selected project.

Required
Idempotent revokeThe endpoint returns 204 No Content whether the direct location grant existed or was already absent. The identity, project, and location remain unchanged.
Effective accessRevoking a location grant does not remove a project grant. If the identity still has project access, it can continue to reach this location through that broader scope.

Request and response

Example requestcURL
curl --request DELETE \
  --url 'https://api.signal.ceyo.ai/v1/embedded-identities/customer-user-4821/projects/e6c96c98-d777-40e0-94ec-48931f57782f/locations/a1308d14-149c-4dd7-a4c5-295ac9090f58/access' \
  --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.

404resource_not_found

The embedded identity, project, or location was not found in this workspace.

429rate_limit_exceeded

Too many requests were made.