Skip to main content

Registration tokens

A registration token lets agent installers register new agents into an organization; create, read, reveal, change, revoke, delete and restore them.

Belongs to: Organizations

Contains: Agents

RegistrationToken object​

A registration token is a secret agent installers present to register new agents into an organization or one below it.

iduuid

The token's id.

organization_iduuid

The organization agents installed with the token register into, or into an organization below it.

patharray of uuid

The organization ids from the top-level organization down to the token's own, then the token's id.

labelstring or null

The token's name; null when it has none.

statusone of the values below

Whether agents can register with the token, worked out on a list at the page's as_of, the same instant for every page of one walk, and on a read of one token when the response is written: revoked once revoked, else expired once expires_at has passed, else active. Whether it is deleted is deleted_at. Passing expires_at does not change updated_at.

  • active Agents can register with it.
  • revoked It was revoked.
  • expired Its expires_at has passed.
created_by_user_idstring or null

The member who created the token. Null when you are not shown that member, when the member has left, or when a workspace token created it.

expires_atdate-time or null

When the token stops working; null when it does not expire.

revoked_atdate-time or null

When the token was revoked; null while it is not.

revocation_reasonstring or null

Why the token was revoked, as the person revoking it wrote.

use_countinteger

How many times agents registered with the token.

last_used_atdate-time or null

When an agent last registered with the token; null until one does.

created_atdate-time

When the token was created.

updated_atdate-time

When the token's record last changed. Every registration with it changes it.

deleted_atdate-time or null

When the token was deleted; null while it is not.

List registration tokens​

GET/workspaces/{workspace_id}/registration-tokens
Preview

Returns the registration tokens you can see, a page at a time, in id order, or least recently changed first with updated_since, never with their secrets. Seeing a token takes organization.read and registration_token.read at its organization. Filter by organization, with or without the organizations below it, by status and by label; filters combine, a row passing every one given. status is worked out at the walk's as_of, the same instant for every page, and a token passing its expires_at does not change its updated_at, so a sync from updated_since misses it: find expired tokens on a full walk. deleted=include or deleted=only returns deleted tokens, and tokens of deleted organizations, too.

curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?status=active" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.read

Needs registration_token.read. registration_token.read applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

Behavior

Retry
Safe to send again
Paging
Cursor, with sync · 1000 a page by default, up to 5000

Path parameters

workspace_iduuidrequired

The workspace's id.

Query parameters

organization_iduuid

Only tokens of this organization.

subtreeboolean

true adds the tokens of every organization below organization_id. true and false are the only values it takes.

Default: false

idarray of string

Only the tokens with these ids. A comma-separated list of at most 100 ids matches any of them.

statusarray of one of the values below

Only tokens whose status is one of these. A comma-separated list matches any of its values. Worked out at the walk's as_of, so a row can start or stop matching without changing: use it on a full walk, never with updated_since.

  • active Agents can register with it.
  • revoked It was revoked.
  • expired Its expires_at has passed.
labelstring

Only tokens of this label: the way to find a token created by a call whose answer was lost. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.

deletedone of the values below

Which tokens to list, by whether they or their organization are deleted.

  • exclude Tokens that are not deleted, in an organization that is not deleted. The default.
  • include Every token, deleted ones and those of deleted organizations included.
  • only Tokens that are deleted or whose organization is.

Default: exclude

updated_sincedate-time

Only tokens changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.

limitinteger

How many tokens a page holds: 1 to 5000, 1000 by default.

Default: 10001 to 5000

cursorstring

The next_cursor of the previous page, with the same filters.

fieldsarray of string

Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: idorganization_idpathlabelstatuscreated_by_user_idexpires_atrevoked_atrevocation_reasonuse_countlast_used_atcreated_atupdated_atdeleted_at

Response 200

registration_tokensarray of RegistrationTokenrequired

The registration tokens on this page.

next_cursorstring or nullrequired

Null on the last page. Otherwise pass it as cursor for the next page.

watermarkdate-timerequired

Pass it as updated_since on your next sync.

as_ofdate-timerequired

The instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, one given twice, or fields naming a field it does not have.No
400APP_API_ERR_BAD_PARAMETERSA filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; parameter names the filter.No
400APP_API_ERR_BAD_PARAMETERSorganization_id is not a UUID, subtree is neither true nor false or comes without it, deleted is not a value it takes, or limit is out of range, cursor cannot be read or was sent with other filters, or updated_since is not a valid time.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold organization.read and registration_token.read. The same refusal comes when the path names a workspace other than the token's own.No

Plus the errors every call can return.

Related

Read a registration token​

GET/workspaces/{workspace_id}/registration-tokens/{id}
Preview

Returns one registration token you can see, deleted or not, without its secret. One you cannot see returns 404, as one that does not exist does.

curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.read

Needs registration_token.read. registration_token.read applies at each organization a grant covers and every organization below it.

Behavior

Retry
Safe to send again

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The registration token's id.

Query parameters

fieldsarray of string

Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: idorganization_idpathlabelstatuscreated_by_user_idexpires_atrevoked_atrevocation_reasonuse_countlast_used_atcreated_atupdated_atdeleted_at

Response 200

registration_tokenRegistrationTokenrequired

The registration token.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, one given twice, or fields naming a field it does not have.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
403APP_API_ERR_NO_PRIVILEGEtoken_scopeno_privilegeYou do not hold organization.read and registration_token.read. The same refusal comes when the path names a workspace other than the token's own.No
404APP_API_ERR_RECORD_NOT_FOUNDNo such registration token, or one you cannot see.No

Plus the errors every call can return.

Related

Create a registration token​

POST/workspaces/{workspace_id}/registration-tokens
PreviewReturns a secret

Creates a token that agent installers present to register into organization_id or an organization below it, and returns it. Needs registration_token.create at that organization. An install that passes an RMM or PSA client id lands in the organization at or below organization_id that records that id, ignoring case, a live one before a deleted one, and fails when the best match is deleted. With no match it creates a new organization directly under organization_id, named from the install's client name, so record the id your RMM passes on the client's organization before deploying.

curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "expires_at": "2026-11-30T00:00:00Z",    "label": "Lakeside Clinic rollout",    "organization_id": "0a9e0000-0000-4000-8000-000000000101"  }'

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.create

Needs registration_token.create. registration_token.create applies at each organization a grant covers and every organization below it.

Behavior

Retry
Read before sending again
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

Request body

organization_iduuidrequired

The organization whose subtree agents installed with the token register into: this organization or one below it. Installs with a client id that matches no organization below it create one directly under it. Required.

labelstring or null

A name for the token. Cleaned, as every name is.

at most 256 characters

expires_atdate-time or null

When the token stops working; leave it out for a token that does not expire. RFC 3339, an offset and fractions of a second allowed; a past time creates an expired token.

Response 200

iduuidrequired

The new registration token's id.

tokenstringrequired

The token an agent installer presents to register. Keep it secret; it can be read again later by anyone holding registration_token.reveal.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_MISSING_PARAMETERorganization_id is left out.No
400APP_API_ERR_BAD_PARAMETERSorganization_id is not a UUID or names a deleted organization, or expires_at is not a valid time.No
400APP_API_ERR_PARAMETER_TOO_LONGlabel is longer than 256 characters.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_scopeno_privilegeYou do not hold registration_token.create at organization_id, or it names no organization you can see. The same refusal comes when the path names a workspace other than the token's own.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Update a registration token​

PATCH/workspaces/{workspace_id}/registration-tokens/{id}
Preview

Changes a registration token's label or expiry; a field left out keeps its value, and an expires_at of null removes the expiry. Moving expires_at later, or to null, makes an expired token active again with the same secret; a revoked token stays revoked. Needs registration_token.revoke at the token's organization.

curl -X PATCH \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "label": "Lakeside Clinic, all sites"  }'

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.revoke

Needs registration_token.revoke. registration_token.revoke applies at each organization a grant covers and every organization below it. registration_token.revoke also admits updating, deleting and restoring a registration token, not only revoking it.

Behavior

Retry
Safe to repeat: ends in the same state
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The registration token's id.

Request body

No field is required. Send no body to accept the defaults.

labelstring or null

The new label. Cleaned, as every name is. null or an empty string clears it.

left out keeps · null clears · empty string clears

at most 256 characters

expires_atdate-time or null

The new expiry. Cleared, the token does not expire. null or an empty string clears it.

left out keeps · null clears · empty string clears

Response 200

iduuidrequired

The id of the row the call created or changed.

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_BAD_PARAMETERSexpires_at is not a valid time.No
400APP_API_ERR_PARAMETER_TOO_LONGlabel is longer than 256 characters.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_scopeno_privilegeThe object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No
409APP_API_ERR_CONFLICTThe token is deleted: restore it first.Read first
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Delete a registration token​

DELETE/workspaces/{workspace_id}/registration-tokens/{id}
PreviewDestructive

Marks a registration token deleted. Needs registration_token.revoke at the token's organization. Deleting a deleted token changes nothing.

curl -X DELETE \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.revoke

Needs registration_token.revoke. registration_token.revoke applies at each organization a grant covers and every organization below it. registration_token.revoke also admits updating, deleting and restoring a registration token, not only revoking it.

Behavior

Retry
Safe to repeat: ends in the same state
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The registration token's id.

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe request carries a body other than nothing, null or {}: a delete takes none, and its options are query parameters; parameter names the body's first field, or body.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_scopeno_privilegeThe object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Restore a deleted registration token​

POST/workspaces/{workspace_id}/registration-tokens/{id}/restore
Preview

Restores a deleted registration token; a revoked or expired token stays so. Needs registration_token.revoke at the token's organization. Restoring a live one changes nothing.

curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/restore" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.revoke

Needs registration_token.revoke. registration_token.revoke applies at each organization a grant covers and every organization below it. registration_token.revoke also admits updating, deleting and restoring a registration token, not only revoking it.

Behavior

Retry
Safe to repeat: ends in the same state
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The registration token's id.

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_scopeno_privilegeThe object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related

Read a registration token's secret​

GET/workspaces/{workspace_id}/registration-tokens/{id}/secret
PreviewReturns a secret

Returns the token agent installers present. Needs registration_token.reveal at the token's organization. Every call is recorded in the audit log. A deleted token returns 404.

curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/secret" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.reveal

Needs registration_token.reveal. registration_token.reveal applies at each organization a grant covers and every organization below it.

Behavior

Retry
Safe to send again
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The registration token's id.

Response 200

tokenstringrequired

The token an agent installer presents to register.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSA query parameter it does not take, or one given twice.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_scopeno_privilegeThe object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No
409APP_API_ERR_CONFLICTThe token is deleted: restore it first.Read first

Plus the errors every call can return.

Related

Revoke a registration token​

POST/workspaces/{workspace_id}/registration-tokens/{id}/revoke
PreviewDestructive

Revokes a registration token: agents can no longer register with it, and agents already registered keep working. Revoking cannot be undone. Needs registration_token.revoke at the token's organization. Revoking a revoked token changes nothing.

curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "reason": "Rollout finished"  }'

Access

Works with
Signed-in person, Personal token, OAuth token, Workspace token
Scope
any of fleet:deployfleet:write
Privilege
registration_token.revoke

Needs registration_token.revoke. registration_token.revoke applies at each organization a grant covers and every organization below it. registration_token.revoke also admits updating, deleting and restoring a registration token, not only revoking it.

Behavior

Retry
Safe to repeat: ends in the same state
Audit log
Recorded

Path parameters

workspace_iduuidrequired

The workspace's id.

iduuidrequired

The registration token's id.

Request body

No field is required. Send no body to accept the defaults.

reasonstring or null

Why the token is revoked, for whoever reads it later.

at most 1024 characters

Response 200

cache_clear_statusone of the values below, or null

Sent when the change has to reach every region's cache: how far it got.

  • ok Every region's cache has the change.
  • failed A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  • disabled This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
cache_clear_messagestring or null

Sent with a cache_clear_status other than ok: what it means, for a person to read.

messagestringrequired

What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

Errors

StatusCodeWhenSend again?
400APP_API_ERR_BAD_PARAMETERSThe URL carries a query parameter, which a write does not take: its fields come from its body.No
400APP_API_ERR_BAD_PARAMETERSid is not a UUID.No
400APP_API_ERR_BAD_PARAMETERSThe body is not a JSON object, is not sent as application/json, names a field the call does not take, or a field has the wrong type; parameter names the field, or Content-Type.No
400APP_API_ERR_PARAMETER_TOO_LONGreason is longer than 1024 characters.No
403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONtoken_scopeno_privilegeThe object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own.No
409APP_API_ERR_CONFLICTThe token is deleted: restore it first.Read first
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related