Skip to main content

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 below

What kind of credential it is.

  • session A person signed in to the SparkLogs app.
  • user_key A personal token.
  • oauth An OAuth token.
  • workspace_key A workspace token.
credential_iduuid or null

The API token's id, the credential_id audit events name; null for a session.

workspace_iduuid or null

The one workspace the API token belongs to; null for a session.

region_idstring or null

The id of the region that workspace's data lives in; null for a session.

scope_restrictionone of the values below, or null

Whether the API token is held to a list of scopes; null for a session.

  • none Every scope its access allows, scopes added later included.
  • listed Only the scopes it lists.
scopesarray of string or null

The scopes the API token carries: every scope when scope_restriction is none; null for a session.

expires_atdate-time or null

When the API token stops working; null when it never expires, and for a session.

Read credential metadata​

GET/credential
Preview

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.

curl -X GET \  "https://engine.sparklogs.app/app-api/credential" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

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 string

Comma-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

credentialCredentialrequired

The credential.

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

Plus the errors every call can return.

Related

Rotate the credential's secret​

POST/credential/rotate
PreviewReturns a secretDestructive

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.

curl -X POST \  "https://engine.sparklogs.app/app-api/credential/rotate" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"

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_iduuidrequired

The API token's id, which rotation does not change.

tokenstringrequired

The 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_iduuidrequired

The workspace the API token belongs to.

user_idstring or nullrequired

The person a personal token acts as; null for a workspace token.

labelstring or nullrequired

The API token's label.

scope_restrictionone of the values belowrequired

Whether the API token is held to a list of scopes.

  • none Every scope its access allows, scopes added later included.
  • listed Only the scopes it lists.
scopesarray of stringrequired

The scopes the API token carries: every scope when scope_restriction is none.

expires_atdate-time or nullrequired

When the API token stops working, which rotation does not change; null when it does not expire.

cache_clear_by_regionmap of string or nullrequired

For 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_statusone of the values belowrequired

Whether every region refuses the old secret.

  • ok Every region refuses the old secret.
  • failed A region could not be reached. The old secret can keep working there until its cache expires.
  • disabled This environment does not clear regional caches. The old secret can keep working until each region's 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_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_CREDENTIAL_NOT_ADMITTEDThe call does not take a credential of this kind: session, oauth.No
409APP_API_ERR_CONFLICTThe token was revoked, deleted or expired, or rotated by another call while this one ran.Read first
413APP_API_ERR_BODY_TOO_LARGEThe body is larger than 1 MiB.No

Plus the errors every call can return.

Related