Create key

Issue a program credential with a cluster, namespace, or collection scope.

POST/keys

PermissionCluster key, or a namespace key managing collection keys within its namespace. Key scopes and actions.

The secret appears only in the create response. Store it securely before continuing.
Namespace and collection scopes require a nonempty actions list. New actions must be a subset of the creator’s actions.
Keys remain active until revoked. They have no expiry field.

Request

https://engine.example.com/keys

POST /keys HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "name": "acme-read",
  "scope": {
    "kind": "namespace",
    "namespace": "acme",
    "actions": [
      "read",
      "search",
      "query"
    ]
  }
}

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

201

The new credential. secret appears only in this response.

{
  "id": "key_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "name": "acme-read",
  "prefix": "gek_",
  "scope": {
    "kind": "namespace",
    "namespace": "acme",
    "actions": [
      "read",
      "search",
      "query"
    ]
  },
  "created_at": "2026-10-06T10:00:00Z",
  "secret": "<GRAPHON_ENGINE_API_KEY>"
}

Request body

namestringrequired

Name that identifies this credential for administration. Use the resource-name grammar: 1–63 lowercase letters, digits, underscores, or hyphens.

scopeobjectrequired

Authority granted to the credential. Choose a cluster, namespace, or collection scope.

Responses

201Key created

The new credential. secret appears only in this response.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

Locationstringrequired

The path of the new resource, by ids.

created_atstring (date-time)required

Time the resource was created, as an ISO 8601 UTC timestamp.

idstringrequired

Immutable administrative key ID with the key_ prefix. This is not the secret used to authenticate.

namestringrequired

Administrative name assigned when this key was created.

prefixstringrequired

Short non-secret prefix used to identify the credential.

revoked_atstring (date-time)optionalaccepts null

Time the key was revoked. Omitted while the key remains active.

scopeobjectrequired

Resource scope and actions granted to this key.

secretstringoptionalaccepts null

Credential returned only once, in the create response. Store it securely on your server. Later list responses omit it.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

409already_exists

The requested resource name already exists.

What to do: Use a different key name, or list the existing keys before continuing.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown