Skip to main content

key

CreateCredential and UpdateCredential require a complete key object. The origin scheme selects how the object is interpreted. Registration validates required fields; the provider checks authentication and access when an object is fetched. Keys are never returned by inspection commands.

All remote keys reject use_default_credentials, regardless of its value. Only the server’s own storage configuration may use its environment identity. See Remote credentials for registration, rotation, and request timing.

S3 keys​

For an s3://bucket origin, supply nonempty string fields region, access_key, and secret_access_key. Temporary credentials additionally require their session_token. The region is the bucket’s region; no server region or environment credentials are substituted.

{"region": "us-west-2", "access_key": "<access-key>",
 "secret_access_key": "<secret-key>"}

Google Cloud Storage keys​

For a gs://bucket origin, supply the complete provider-issued service-account JSON key. type must be service_account; client_email, private_key, and token_uri must be nonempty strings. Keep the provider’s other fields. Registration does not prove that the private key can sign or that the account has access to the bucket. Verify access by retrieving a small object.

HTTPS keys and transport​

Every HTTPS origin requires registration, including anonymous origins. Each origin has its own key. CreateCredential and UpdateCredential normalize the hostname to lowercase and omit port 443; object URLs must already use the canonical spelling below.

HTTPS key forms

Authentication

key value

Requirements

Anonymous

{}

Register the origin with an empty object.

HTTP Basic

{"username": "reader", "password": "<origin-password>"}

Both fields are strings; username must be nonempty and contain no colon. Password may be empty.

Bearer

{"bearer_token": "<origin-token>"}

Nonempty string without spaces.

These forms are exclusive: extra fields or mixed Basic/Bearer keys are rejected. Values may not contain control characters and each is limited to 8192 bytes. A database login token and a remote origin’s bearer token serve different systems; use the token issued by the remote origin here.

For example, an administrator can register an anonymous origin:

[{"CreateCredential": {
  "origin": "https://media.example.com",
  "key": {}
}}]

Replace the example origin with a public HTTPS service you control or are allowed to read. Objects on that origin can then be referenced with full URLs, such as https://media.example.com/images/sample.jpg, in commands supporting url. Choose the command’s copy/reference behavior explicitly; ApertureDB cannot write to or delete objects at an HTTPS origin.

URL and transport restrictions​

  • Use the lowercase scheme https:// and a lowercase DNS hostname containing a dot. IP literals, trailing-dot hostnames, and private, loopback, link-local, or other non-public destinations are refused. The connected address is checked for each request, including after DNS resolution.

  • Omit the default port: https://media.example.com:443 is rejected. A nondefault port is allowed from 1–65535, without leading zeroes, and is part of the exact origin. For example, https://media.example.com:8443 requires its own origin registration.

  • Object URLs need a slash before the path. URLs may not contain query strings, fragments, backslashes, whitespace, or non-ASCII characters. Consequently, query-signed URLs are not supported. Use an origin credential instead.

  • The server validates the TLS certificate and hostname. Redirects are not followed; publish the final URL with an HTTP 200 response. Compressed HTTP bodies (Content-Encoding) are refused. A HEAD size check must return a valid Content-Length.

  • When the database uses cloud object storage, its own bucket and the protected cloud-storage hostnames cannot be accessed through this HTTPS mechanism. Use an s3:// or gs:// credential for those resources.

Limits and recovery​

The defaults are 16 MiB per object, a 10-second fetch timeout, and four concurrent operations/readers per server process. See HTTPS origin limits for their maxima and the independent per-query budget (64 MiB, 32 requests, 60 seconds, and two active fetches).

The generic error HTTPS object request refused or failed deliberately does not expose the URL, credentials, or remote response. Check, in order, that the exact origin is registered; the key is current; the URL meets the rules above; DNS and the TLS certificate are valid; and the origin returns an uncompressed HTTP 200 response within the size/time budgets. Reduce query size or concurrent work before retrying an overload. Check the origin’s logs for authentication or availability failures without copying secrets into support logs.