Credential
The credential that authenticates a call: read what it is and which workspace it belongs to, or give a token a new secret.
A workspace token reads its credential to learn its workspace id, which every other path needs.
Belongs to: Workspaces, Regions
Contains: Audit events
Credential object
The credential that authenticated a call: a signed-in session or an API token, with the workspace a token belongs to, its scopes and when it expires.
kindone of the values belowWhat kind of credential it is.
sessionA person signed in to the SparkLogs app.user_keyA personal token.oauthAn OAuth token.workspace_keyA workspace token.
credential_id uuid or nullThe API token's id, the credential_id audit events name; null for a session.
workspace_id uuid or nullThe one workspace the API token belongs to; null for a session.
region_id string or nullThe id of the region that workspace's data lives in; null for a session.
scope_restriction one of the values below, or nullWhether the API token is held to a list of scopes; null for a session.
noneEvery scope its access allows, scopes added later included.listedOnly the scopes it lists.
scopesarray of string or nullThe scopes the API token carries: every scope when scope_restriction is none; null for a session.
expires_at date-time or nullWhen the API token stops working; null when it never expires, and for a session.
Read credential metadata
/credential Returns what the credential on this request is: a session, or an API token with its id, the one workspace it belongs to, that workspace's region, its scopes and when it expires. A workspace token calls it to learn its workspace id.
- Request
- Response
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/credential" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/credential" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/credential" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "credential": { "kind": "workspace_key", "credential_id": "4b1d0000-0000-4000-8000-000000000803", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "region_id": "us-central", "scope_restriction": "listed", "scopes": [ "workspace:read", "fleet:deploy" ], "expires_at": "2027-11-10T09:00:00Z" }, "message": "credential retrieved"}Access
- Works with
- Signed-in person, Personal token, OAuth token, Workspace token
Needs no privilege: it reads only the credential that authenticates the call.
Behavior
- Retry
- Safe to send again
Query parameters
fieldsarray of stringComma-separated top-level fields of each object to return instead of the default set.
Sent by default: kindcredential_idworkspace_idregion_idscope_restrictionscopesexpires_at
Response 200
The credential.
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.NoPlus the errors every call can return.
Related
Rotate the credential's secret
/credential/rotate Gives the personal token or workspace token that authenticates this call a new secret and returns it, once. The old secret stops working at once on this API, and cache_clear_status says whether every other SparkLogs service refuses it. The token's id, label, scopes, grants and expiry stay. When the token was revoked, deleted or rotated while the call ran, nothing changes and the call returns 409. The rotation is recorded in the audit log. When cache_clear_status is not ok, a region the change did not reach can act on the earlier state for up to 15 minutes.
- Request
- Response
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/credential/rotate" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/credential/rotate" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/credential/rotate" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "token rotated", "credential_id": "4b1d0000-0000-4000-8000-000000000803", "token": "sl_us_EXAMPLE_NOT_A_REAL_TOKEN", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "user_id": null, "label": "RMM deployment", "scope_restriction": "listed", "scopes": [ "workspace:read", "fleet:deploy" ], "expires_at": "2027-11-10T09:00:00Z", "cache_clear_by_region": { "us-central": "ok" }, "cache_clear_status": "ok"}Access
- Works with
- Personal token, Workspace token
Needs no privilege: the token that authenticates the call acts on itself and nothing else.
Behavior
- Retry
- Read before sending again
- Audit log
- Recorded
Response 200
credential_id uuidrequiredThe API token's id, which rotation does not change.
tokenstringrequiredThe new secret. It is sent only this once and cannot be read again. The old secret is refused in every region cache_clear_status says the change reached.
workspace_id uuidrequiredThe workspace the API token belongs to.
user_id string or nullrequiredThe person a personal token acts as; null for a workspace token.
labelstring or nullrequiredThe API token's label.
scope_restriction one of the values belowrequiredWhether the API token is held to a list of scopes.
noneEvery scope its access allows, scopes added later included.listedOnly the scopes it lists.
scopesarray of stringrequiredThe scopes the API token carries: every scope when scope_restriction is none.
expires_at date-time or nullrequiredWhen the API token stops working, which rotation does not change; null when it does not expire.
cache_clear_by_region map of string or nullrequiredFor each region whose cache may still hold the old secret, whether that cache dropped it: ok, failed or disabled. Null when there was nothing to drop.
cache_clear_status one of the values belowrequiredWhether every region refuses the old secret.
okEvery region refuses the old secret.failedA region could not be reached. The old secret can keep working there until its cache expires.disabledThis environment does not clear regional caches. The old secret can keep working until each region's 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 The body is not a JSON object, is not sent as application/json, or names a field: the call takes none.No403APP_API_ERR_CREDENTIAL_NOT_ADMITTED The call does not take a credential of this kind: session, oauth.No409APP_API_ERR_CONFLICT The token was revoked, deleted or expired, or rotated by another call while this one ran.Read first413APP_API_ERR_BODY_TOO_LARGE The body is larger than 1 MiB.NoPlus the errors every call can return.