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
- GET
List registration tokens/workspaces /{workspace_id} /registration-tokens - GET
Read a registration token/workspaces /{workspace_id} /registration-tokens /{id} - POST
Create a registration token/workspaces /{workspace_id} /registration-tokens - PATCH
Update a registration token/workspaces /{workspace_id} /registration-tokens /{id} - DELETE
Delete a registration token/workspaces /{workspace_id} /registration-tokens /{id} - POST
Restore a deleted registration token/workspaces /{workspace_id} /registration-tokens /{id} /restore - GET
Read a registration token's secret/workspaces /{workspace_id} /registration-tokens /{id} /secret - POST
Revoke a registration token/workspaces /{workspace_id} /registration-tokens /{id} /revoke
RegistrationToken object
A registration token is a secret agent installers present to register new agents into an organization or one below it.
iduuidThe token's id.
organization_id uuidThe organization agents installed with the token register into, or into an organization below it.
patharray of uuidThe organization ids from the top-level organization down to the token's own, then the token's id.
labelstring or nullThe token's name; null when it has none.
statusone of the values belowWhether 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.
activeAgents can register with it.revokedIt was revoked.expiredItsexpires_athas passed.
created_by_user_id string or nullThe 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_at date-time or nullWhen the token stops working; null when it does not expire.
revoked_at date-time or nullWhen the token was revoked; null while it is not.
revocation_reason string or nullWhy the token was revoked, as the person revoking it wrote.
use_count integerHow many times agents registered with the token.
last_used_at date-time or nullWhen an agent last registered with the token; null until one does.
created_at date-timeWhen the token was created.
updated_at date-timeWhen the token's record last changed. Every registration with it changes it.
deleted_at date-time or nullWhen the token was deleted; null while it is not.
List registration tokens
/workspaces/{workspace_id}/registration-tokens 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.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?status=active" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?status=active" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "status": "active", },)response.raise_for_status(){ "as_of": "2026-11-10T09:01:00Z", "message": "registration tokens retrieved", "next_cursor": null, "registration_tokens": [ { "id": "7e0c0000-0000-4000-8000-000000000301", "organization_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "7e0c0000-0000-4000-8000-000000000301" ], "label": "Lakeside Clinic rollout", "status": "active", "created_by_user_id": "AlexRiveraExampleUserId00001", "expires_at": "2026-11-30T00:00:00Z", "revoked_at": null, "revocation_reason": null, "use_count": 1, "last_used_at": "2026-11-03T12:00:00Z", "created_at": "2026-11-03T11:00:00Z", "updated_at": "2026-11-03T12:00:00Z", "deleted_at": null }, { "id": "7e0c0000-0000-4000-8000-000000000303", "organization_id": "0a9e0000-0000-4000-8000-000000000100", "path": [ "0a9e0000-0000-4000-8000-000000000100", "7e0c0000-0000-4000-8000-000000000303" ], "label": "Northwind clients agents", "status": "active", "created_by_user_id": "AlexRiveraExampleUserId00001", "expires_at": null, "revoked_at": null, "revocation_reason": null, "use_count": 1, "last_used_at": "2026-11-04T09:00:00Z", "created_at": "2026-11-01T10:00:00Z", "updated_at": "2026-11-04T09:00:00Z", "deleted_at": null } ], "watermark": "2026-11-10T09:00:00Z"}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_id uuidrequiredThe workspace's id.
Query parameters
organization_id uuidOnly tokens of this organization.
subtreebooleantrue adds the tokens of every organization below organization_id. true and false are the only values it takes.
idarray of stringOnly the tokens with these ids. A comma-separated list of at most 100 ids matches any of them.
statusarray of one of the values belowOnly 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.
activeAgents can register with it.revokedIt was revoked.expiredItsexpires_athas passed.
labelstringOnly 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 belowWhich tokens to list, by whether they or their organization are deleted.
excludeTokens that are not deleted, in an organization that is not deleted. The default.includeEvery token, deleted ones and those of deleted organizations included.onlyTokens that are deleted or whose organization is.
updated_since date-timeOnly tokens changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.
limitintegerHow many tokens a page holds: 1 to 5000, 1000 by default.
cursorstringThe next_cursor of the previous page, with the same filters.
fieldsarray of stringComma-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
The registration tokens on this page.
next_cursor string or nullrequiredNull on the last page. Otherwise pass it as cursor for the next page.
watermarkdate-timerequiredPass it as updated_since on your next sync.
as_of date-timerequiredThe 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.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, one given twice, or fields naming a field it does not have.NoAPP_API_ERR_BAD_PARAMETERS A 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.NoAPP_API_ERR_BAD_PARAMETERS organization_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.No403APP_API_ERR_NO_PRIVILEGE token_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.NoPlus the errors every call can return.
Related
Read a registration token
/workspaces/{workspace_id}/registration-tokens/{id} 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.
- Request
- Response
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "registration token retrieved", "registration_token": { "id": "7e0c0000-0000-4000-8000-000000000301", "organization_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "7e0c0000-0000-4000-8000-000000000301" ], "label": "Lakeside Clinic rollout", "status": "active", "created_by_user_id": "AlexRiveraExampleUserId00001", "expires_at": "2026-11-30T00:00:00Z", "revoked_at": null, "revocation_reason": null, "use_count": 1, "last_used_at": "2026-11-03T12:00:00Z", "created_at": "2026-11-03T11:00:00Z", "updated_at": "2026-11-03T12:00:00Z", "deleted_at": null }}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe registration token's id.
Query parameters
fieldsarray of stringComma-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
The registration token.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, one given twice, or fields naming a field it does not have.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.No403APP_API_ERR_NO_PRIVILEGE token_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.No404APP_API_ERR_RECORD_NOT_FOUND No such registration token, or one you cannot see.NoPlus the errors every call can return.
Related
Create a registration token
/workspaces/{workspace_id}/registration-tokens 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.
- Request
- Response
- curl
- PowerShell
- Python
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" }'$body = @{ expires_at = "2026-11-30T00:00:00Z" label = "Lakeside Clinic rollout" organization_id = "0a9e0000-0000-4000-8000-000000000101"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "expires_at": "2026-11-30T00:00:00Z", "label": "Lakeside Clinic rollout", "organization_id": "0a9e0000-0000-4000-8000-000000000101", },)response.raise_for_status(){ "message": "registration token created", "id": "7e0c0000-0000-4000-8000-000000000301", "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"}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_id uuidrequiredThe workspace's id.
Request body
organization_id uuidrequiredThe 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 nullA name for the token. Cleaned, as every name is.
expires_at date-time or nullWhen 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
iduuidrequiredThe new registration token's id.
tokenstringrequiredThe token an agent installer presents to register. Keep it secret; it can be read again later by anyone holding registration_token.reveal.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS The 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.NoAPP_API_ERR_MISSING_PARAMETER organization_id is left out.NoAPP_API_ERR_BAD_PARAMETERS organization_id is not a UUID or names a deleted organization, or expires_at is not a valid time.NoAPP_API_ERR_PARAMETER_TOO_LONG label is longer than 256 characters.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Update a registration token
/workspaces/{workspace_id}/registration-tokens/{id} 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.
- Request
- Response
- curl
- PowerShell
- Python
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" }'$body = @{ label = "Lakeside Clinic, all sites"}Invoke-RestMethod -Method Patch ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.patch( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "label": "Lakeside Clinic, all sites", },)response.raise_for_status(){ "message": "registration token updated", "id": "7e0c0000-0000-4000-8000-000000000301"}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe registration token's id.
Request body
No field is required. Send no body to accept the defaults.
labelstring or nullThe new label. Cleaned, as every name is. null or an empty string clears it.
left out keeps · null clears · empty string clears
expires_at date-time or nullThe 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
iduuidrequiredThe id of the row the call created or changed.
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The 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.NoAPP_API_ERR_BAD_PARAMETERS expires_at is not a valid time.NoAPP_API_ERR_PARAMETER_TOO_LONG label is longer than 256 characters.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_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.No409APP_API_ERR_CONFLICT The token is deleted: restore it first.Read first413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Delete a registration token
/workspaces/{workspace_id}/registration-tokens/{id} Marks a registration token deleted. Needs registration_token.revoke at the token's organization. Deleting a deleted token changes nothing.
- Request
- Response
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "registration token deleted"}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe registration token's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The 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.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Restore a deleted registration token
/workspaces/{workspace_id}/registration-tokens/{id}/restore 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.
- Request
- Response
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/restore" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/restore" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "registration token restored"}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe registration token's id.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_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.No413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.
Related
Read a registration token's secret
/workspaces/{workspace_id}/registration-tokens/{id}/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.
- Request
- Response
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/secret" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/secret" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "registration token retrieved", "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe registration token's id.
Response 200
tokenstringrequiredThe token an agent installer presents to register.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS A query parameter it does not take, or one given twice.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_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.No409APP_API_ERR_CONFLICT The token is deleted: restore it first.Read firstPlus the errors every call can return.
Related
Revoke a registration token
/workspaces/{workspace_id}/registration-tokens/{id}/revoke 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.
- Request
- Response
- curl
- PowerShell
- Python
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" }'$body = @{ reason = "Rollout finished"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "reason": "Rollout finished", },)response.raise_for_status(){ "message": "registration token revoked"}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_id uuidrequiredThe workspace's id.
iduuidrequiredThe registration token's id.
Request body
No field is required. Send no body to accept the defaults.
reasonstring or nullWhy the token is revoked, for whoever reads it later.
Response 200
cache_clear_status one of the values below, or nullSent when the change has to reach every region's cache: how far it got.
okEvery region's cache has the change.failedA region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.disabledThis 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_message string or nullSent with a cache_clear_status other than ok: what it means, for a person to read.
messagestringrequiredWhat the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.
Errors
400APP_API_ERR_BAD_PARAMETERS The URL carries a query parameter, which a write does not take: its fields come from its body.NoAPP_API_ERR_BAD_PARAMETERS id is not a UUID.NoAPP_API_ERR_BAD_PARAMETERS The 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.NoAPP_API_ERR_PARAMETER_TOO_LONG reason is longer than 1024 characters.No403APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION token_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.No409APP_API_ERR_CONFLICT The token is deleted: restore it first.Read first413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.