Revoke an API key

DELETE/v1alpha1/admin/keys/{id}keys.write

Revokes an API key. Revocation takes effect on the answering node immediately and across all other nodes within EXOFIND_AUTH_REFRESH_INTERVAL, as nodes accept cached keys until their next storage read.

What a key allows cannot be changed. To change permissions, create a replacement key, migrate clients to the new key, and revoke the old key. To replace only the credential, keeping everything the key allows, use actions/rotate. The root key is not stored in key storage and cannot be revoked through the API.

The answering node refuses to revoke two keys, because it would not start again without them: the last key granted keys.write when the node has no root key, and the key named by EXOFIND_AUTH_ANONYMOUS_KEY. Create a replacement, or point the configuration elsewhere, and send the request again.

Served by whichever node receives the request.

Request

HTTP

DELETE /v1alpha1/admin/keys/4ff6b760264c1918
Authorization: Bearer <key>

curl

curl -X DELETE "http://localhost:8080/v1alpha1/admin/keys/4ff6b760264c1918" \
  -H "Authorization: Bearer $EXOFIND_API_KEY"

JavaScript

const apiKey = process.env.EXOFIND_API_KEY;

const response = await fetch("http://localhost:8080/v1alpha1/admin/keys/4ff6b760264c1918", {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${apiKey}`
  }
});

const result = await response.json();

Java

String apiKey = System.getenv("EXOFIND_API_KEY");

HttpRequest request = HttpRequest.newBuilder()
  .uri(URI.create("http://localhost:8080/v1alpha1/admin/keys/4ff6b760264c1918"))
  .header("Authorization", "Bearer " + apiKey)
  .DELETE()
  .build();

HttpResponse<String> response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());

Go

apiKey := os.Getenv("EXOFIND_API_KEY")

request, err := http.NewRequest("DELETE", "http://localhost:8080/v1alpha1/admin/keys/4ff6b760264c1918", nil)
if err != nil {
  log.Fatal(err)
}

request.Header.Set("Authorization", "Bearer "+apiKey)

response, err := http.DefaultClient.Do(request)

Response204

No body. The status is the whole answer.

Path parameters

idstringrequired

ID of the key to revoke.

Responses

204

The key was revoked.

401

The request carries no credential this node accepts. Absent, malformed, unknown and lapsed keys are all answered alike, so a refusal cannot be used to find out which keys exist. The response carries WWW-Authenticate: Bearer.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:unauthenticated

The request carries no credential this node accepts.

403

The API key does not have the keys.write permission.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:forbidden

The key is accepted but does not hold the `keys.write` permission.

404

No key has this ID.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:key:not_found

No key is stored under this ID.

409

The key could not be revoked. The stored keys are unchanged.

ErrorResponse

The body of every failed request. Error codes use colon-separated namespaces such as index:field:name_invalid, are stable across API versions, and are never renamed or reused, so clients match on code rather than on message. See Errors.

codestring

Identifies the failure type. For validation failures, this is validation and the individual problems are listed in errors. For all other failures, this matches the code of the single entry in errors.

Example

"validation"

messagestring

Human-readable message for log output. Match on code rather than on message. When a validation failure contains one problem, this is that problem's message. When it contains several, it reads Request contains N errors.

Example

"Request contains 2 errors"

errorsErrorDetail[]

All problems found in the request. A validation failure reports every field with a problem, so a caller can fix them in one pass rather than one request at a time.

Example

{
  "code": "index:field:primary_key:multiple_unsupported",
  "message": "Field `id` is marked as a primary key and multiple, primary keys can not have multiple values",
  "path": "id"
}

4 properties

codestring

The error code identifying this specific problem.

Example

"index:field:primary_key:multiple_unsupported"

messagestring

Human-readable description of this problem.

Example

"Field `id` is marked as a primary key and multiple, primary keys can not have multiple values"

pathstring

Location of the offending value in the request, such as fields.title or documents[1].nonexistent. Names join with ., one element of a list reads [n] counted from zero, and a key of a free-form map such as metadata goes in brackets and double quotes when it holds a dot or a bracket, as metadata["build.sha"]. A field inside an object field carries its own dotted path, so a path here reaches a field the same way a query does. Omitted when the problem applies to the request as a whole. See API conventions.

Example

"id"

argumentsmap of string

The values the message was rendered with, so a client can render a message of its own from the code.

1 property

<key>string

Error codes

auth:key:last_administrator

The key is the last one granted `keys.write` and the node has no root key, so revoking it would leave nobody able to create another.

auth:key:in_use_as_anonymous

`EXOFIND_AUTH_ANONYMOUS_KEY` names this key on the answering node, so revoking it would stop that node from starting.

storage:unavailable

The node is not configured with key storage.

storage:io_error

Key storage answered with an error. Send the request again.

storage:conflict

Other nodes kept changing the stored keys. The stored keys are unchanged; send the request again.

Authorization

Permission

keys.write

Checked on

The deployment, not one index

Roles

admin

An API key sent as a bearer token, such as Authorization: Bearer exok_4ff6b760264c1918_ePQcdT1O9HSATZoXfDbT8hhHGsP9VpZH. A key carries grants that pair permissions with index patterns; the permission each endpoint needs is named beside it. Nodes running with EXOFIND_AUTH_MODE=none accept requests without a credential, and a node with EXOFIND_AUTH_ANONYMOUS_KEY set serves requests that carry none with the permissions of that key.