Revoke a runner enrollment

POST/api/workspaces/{workspace_id}/runner-enrollments/{enrollment_id}/revoke

revokeRunnerEnrollment

Stop the enrollment's token from registering runners. `cascade` also deregisters every runner registered through it; `node_id` instead deregisters only that machine's runner and keeps the enrollment. A deregistered runner's running job goes back to the queue. Same permission as creating the enrollment; 404 for one the caller cannot manage, or a `node_id` with no runner.

Requires authentication using a bearer token or a session cookie — see tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/workspaces/WORKSPACE_ID/runner-enrollments/ENROLLMENT_ID/revoke' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

fetch

fetch("https://neosource.dev/api/workspaces/WORKSPACE_ID/runner-enrollments/ENROLLMENT_ID/revoke", {
  method: "POST",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

Path parameters

workspace_idrequired: string
enrollment_idrequired: string

Request bodyrequired

application/json

RevokeRunnerEnrollmentRequest

object

Revoke an enrollment (`POST /api/workspaces/{workspace_id}/runner-enrollments/{enrollment_id}/revoke`). With neither field, the token stops working and existing runners keep running.

cascade: boolean
Also deregister every runner registered through it; their running jobs go back to the queue.
node_id: string | null
Deregister only this machine's runner and keep the enrollment. Not combinable with `cascade`.

Responses

200Revoked

application/json

RevokeRunnerEnrollmentResponse

object

deregistered_runnersrequired

integerint64

Runners deregistered by this call.

enrollmentrequired

RunnerEnrollmentResponse

object

One runner enrollment. Never carries the token.

actor_id: string | null
The account actor-bound runners are bound to (always the creator).
bindingrequired: RunnerBindingKind
created_atrequired: integerint64
created_by_accountrequired: string
The account that created it. Registration re-checks that this account still holds the creating permission.
created_by_token_id: string | null
The token that created it, when one did: registration also needs that token to still be live and to still permit the action.
ephemeralrequired: boolean
expires_at: integer | nullint64
Epoch ms; `null` = never.
idrequired: string
kindrequired: RunnerEnrollmentKind
max_uses: integer | nullint32
`null` = unbounded.
revoked_at: integer | nullint64
Epoch ms; `null` = live.
scoperequired: RunnerScope
usesrequired: integerint32
vm_backendsrequired: array
itemsVmBackendKind
workspace_id: string | null

403Forbidden — one of: forbidden, needs_scope

application/json

one of

ErrorForbidden
NeedsScopeError
object
`403` body returned when a classic OAuth token is asked for something its granted scopes do not cover — an explicit private listing without `repo`, or the one-click GitHub mirror without `admin:public_key`. `scope` names the missing grant so the client can say exactly what the token lacks. There is no elevation route to widen it any more (a re-link goes through the GitHub App, whose tokens carry no scopes), so the client's answer is to say so, never to start a handshake.
errorrequired
string
Always `needs_scope` — this body exists to carry the extra fields that kind needs.
"needs_scope"
scoperequired
string
The provider scope to request via elevation (e.g. `"repo"`).

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
404Not Found — one of: not_found
409Conflict — one of: already_exists, conflict
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

`RunnerBindingKind`

string

Which trust binding a job executed under (ADR 0056 §1/§7). Serialized on the wire and in `workflow_run_jobs.executed_on` as the `snake_case` strings `hosted` / `workspace` / `actor`.

"hosted""workspace""actor"

`RunnerEnrollmentKind`

string

How an enrollment is presented (ADR 0153 §1). Only `Token` is creatable today; `Workload` is the projected-ServiceAccount-token kind, whose columns exist but which no route creates or redeems yet.

"token""workload"

`RunnerScope`

string

Whether a runner is hosted by the platform (per [ADR 0014]) or long-poll-attached from outside.

"hosted""self_hosted""local"

`VmBackendKind`

string

"docker_shell""kata_clh""kata_fc""lib_krun""k8s_runc""cloud_hypervisor"