Identities

Endpoints for managing clients and users. Both clients and users support metadata which can be used to store arbitrary key-value pairs. Note that when updating a client or user, metadata will replace the existing metadata and not be merged with it.

Get clients Build and above

Use this endpoint to get a paginated list of client identifiers.

GET/v1/headless/clients

Query parameters

Field	Type	Required	Default	Description	Options
`length`	`number`	No	`100`		—
`page`	`number`	No	`0`		—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/clients?length=100&page=0" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

[
  {
    "userCount": 12,
    "clientIdentifier": "client_123",
    "created": "2026-09-26T21:41:01.597Z",
    "updated": "2026-09-26T21:41:01.597Z"
  }
]

Get client Build and above

Use this endpoint to get a client by identifier.

GET/v1/headless/client/{identifier}

Path parameters

Field	Description	Options
`identifier`	Your stable client identifier	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/client/client_123" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

{
  "userCount": 12,
  "clientIdentifier": "client_123",
  "created": "2026-09-26T21:41:01.598Z",
  "updated": "2026-09-26T21:41:01.598Z"
}

Get users Build and above

Use this endpoint to get a paginated list of users. You can optionally filter by clientIdentifier.

GET/v1/headless/users

Query parameters

Field	Type	Required	Default	Options
`length`	`number`	No	`100`	—
`page`	`number`	No	`0`	—
`clientIdentifier`	`string`	No	—	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/users?length=100&page=0&clientIdentifier=client_123" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

[
  {
    "identifier": "user_123",
    "clientIdentifier": "client_123",
    "name": "example",
    "avatar": "example",
    "testMode": false,
    "created": "2026-09-26T21:41:01.598Z",
    "updated": "2026-09-26T21:41:01.598Z"
  }
]

Get user Build and above

Use this endpoint to get a user by identifier.

GET/v1/headless/user/{identifier}

Path parameters

Field	Description	Options
`identifier`	Your stable user identifier	—

Examples

cURL request

curl --request GET \
  --url "https://api.coassemble.com/api/v1/headless/user/user_123" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Response

JSON response

{
  "identifier": "user_123",
  "clientIdentifier": "client_123",
  "name": "example",
  "avatar": "example",
  "testMode": false,
  "created": "2026-09-26T21:41:01.598Z",
  "updated": "2026-09-26T21:41:01.598Z"
}

Update client Build and above

Use this endpoint to update a client's metadata.

PUT/v1/headless/client/{identifier}

Path parameters

Field	Description	Options
`identifier`	Your stable client identifier	—

Body parameters

Field	Type	Required	Desc	Options
`metadata`	`object`	No	Arbitrary metadata to attach to the client	—

Examples

cURL request

curl --request PUT \
  --url "https://api.coassemble.com/api/v1/headless/client/client_123" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "metadata": {
        "department": "Sales"
    }
}'

Response

JSON response

{
  "userCount": 12,
  "clientIdentifier": "client_123",
  "created": "2026-09-26T21:41:01.598Z",
  "updated": "2026-09-26T21:41:01.598Z"
}

Delete client Build and above

Use this endpoint to delete all objects associated with a clientIdentifier.

DELETE/v1/headless/client/{identifier}

Path parameters

Field	Description	Options
`identifier`	Your stable client identifier	—

Examples

cURL request

curl --request DELETE \
  --url "https://api.coassemble.com/api/v1/headless/client/client_123" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"

Update user Build and above

Use this endpoint to update a user's metadata.

PUT/v1/headless/user/{identifier}

Path parameters

Field	Description	Options
`identifier`	Your stable user identifier	—

Body parameters

Field	Type	Required	Desc	Options
`clientIdentifier`	`string`	No	The client this user belongs to	—
`metadata`	`object`	No	Arbitrary metadata to merge onto the user	—
`name`	`string`	No	Display name (shorthand for metadata.name)	—
`avatar`	`string`	No	Avatar URL (shorthand for metadata.avatar)	—

Examples

cURL request

curl --request PUT \
  --url "https://api.coassemble.com/api/v1/headless/user/user_123" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "clientIdentifier": "client_123",
    "metadata": {
        "department": "Sales"
    },
    "name": "example",
    "avatar": "example"
}'

Response

JSON response

{
  "identifier": "user_123",
  "clientIdentifier": "client_123",
  "name": "example",
  "avatar": "example",
  "testMode": false,
  "created": "2026-09-26T21:41:01.598Z",
  "updated": "2026-09-26T21:41:01.598Z"
}

Delete user Build and above

Use this endpoint to delete a user by their identifier. You can choose what to do with any courses associated with this identifier.

DELETE/v1/headless/user/{identifier}

Path parameters

Field	Description	Options
`identifier`	Your stable user identifier	—

Query parameters

Field	Type	Required	Default	Options
`clientIdentifier`	`string`	No	—	—
`action`	`string`	No	—	`reallocatedeleteignore`
`reallocateTo`	`string`	No	—	—

Examples

cURL request

curl --request DELETE \
  --url "https://api.coassemble.com/api/v1/headless/user/user_123?clientIdentifier=client_123&action=reallocate&reallocateTo=example" \
  --header "Authorization: COASSEMBLE:YOUR_WORKSPACE_ID:YOUR_API_KEY"