Invalidate Token

DELETE /{namespace}/{principalType}/{principalId}/tokens/{tokenId}

Revokes the access key's active record so subsequent website and API requests using that bearer are rejected. The token ID is the ID returned by create/list and carried in its JWT jti claim. Only the owner may revoke it. OAuth connections explicitly approved with a website key are independent grants and must be revoked separately.

Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.

Required scope

Any authenticated access token

Path parameters

tokenIdstringRequired: The token identifier (partial ID)
namespacestringRequired: The namespace of the principal
principalTypestringRequired: The type of principal
principalIdstringRequired: The ID of the principal

Header parameters

Idempotency-KeystringRequired

Client-chosen key that makes a non-idempotent request retry-safe, following draft-ietf-httpapi-idempotency-key-header. A committed response is stored for 24 hours and replayed for the same principal, operation, key and payload. Missing key returns 400 IDEMPOTENCY_KEY_REQUIRED, a key longer than 255 characters returns 400 IDEMPOTENCY_KEY_INVALID, the same key with a different payload returns 422, and the same key while the first request is still in flight returns 409. Requests rolled back before external provider attempts do not consume the key. Group mutations retain terminal failed responses after provider attempts together with received provider truth; their operation contract defines these replayable outcomes.

minLength: 1

maxLength: 255

If-MatchstringRequired

The quoted strong entity tag of the resource the client last read (its `etag` field or `ETag` response header). The mutation is applied only when it still matches: a stale value returns 412 PRECONDITION_FAILED and a missing header returns 428 PRECONDITION_REQUIRED. Wildcards are accepted only where the operation explicitly permits them.

minLength: 1

Returns

200

Stored resource returned; authorized retries replay the same committed response for 24 hours.

No response body.

Errors

400 IDEMPOTENCY_KEY_REQUIRED

Invalid request or missing Idempotency-Key.

Check the request fields and any validation details, then correct the payload.

401 UNAUTHORIZED

Authentication required.

Obtain a valid access token, then retry.

403 FORBIDDEN

Caller lacks resource permission.

Check the linked account and its permissions for the device or resource.

404 NOT_FOUND

The addressed resource does not exist.

Verify the target identifier and that its endpoint or plugin route still exists.

409 IDEMPOTENCY_KEY_IN_FLIGHT

The idempotency request is in flight.

Check the device’s current mode or state. Retry only after the conflict is resolved.

412 PRECONDITION_FAILED

The resource version changed.

Inspect the returned code and family and follow the error handling guide.

422 IDEMPOTENCY_KEY_REUSED

The same key was used for a different request.

Correct the rejected value using the constraints in the error details or request schema.

428 PRECONDITION_REQUIRED

If-Match is required for replacement or delete.

Inspect the returned code and family and follow the error handling guide.

500 INTERNAL

The operation could not be committed.

Retry with backoff only when the operation is safe to repeat. Include the error code when reporting persistent failures.