key

key is the service-specific credential object used by CreateCredential and UpdateCredential. Creation requires the object. On update, omitting key preserves it; supplying one replaces the entire object, so include every member needed by the service.

All registered credentials reject a use_default_credentials member, regardless of its value. That option belongs only to the server’s own storage configuration. Registered credentials must supply their own identity, or use an empty HTTPS key for an anonymous origin.

AWS and GCP key members are stored without a service-specific validity check at registration. Missing or invalid members can therefore fail when ApertureDB opens the remote connection or fetches an object. A successful CreateCredential or UpdateCredential response does not establish that the key can authenticate. HTTPS authentication forms and origins are validated during registration.

AWS keys

For service: "aws", the key contains the following members. Required fields are needed to authenticate; registration does not validate their types or completeness.

Member	Type / required for use	Behavior
region	nonempty string / required	Region of the S3 bucket. No environment or server-region fallback is used.
access_key	nonempty string / required	AWS access key ID. The field is named access_key, not access_key_id.
secret_access_key	nonempty string / required	Secret paired with access_key; no default.
session_token	string / conditional	Omitted for long-lived key pairs; provide the matching token for temporary credentials. A token alone cannot replace the key pair.

The region describes the resources, not the caller’s location. Register separate credentials for buckets in different regions; requests signed for the wrong region fail instead of being redirected. Extra key members are retained but are not used by the AWS adapter, except that use_default_credentials is always rejected. No field-specific length limit is imposed here; the query’s message-size limit and AWS authentication rules still apply.

GCP keys

For service: "gcp", pass a service-account JSON key. This path does not select an authorized-user, access-token, external-account, or application-default credential merely because such fields appear in the object. Keep the complete key issued for the service account.

ApertureDB passes the key to the Google Cloud C++ service-account parser, which consumes the fields below. Validation and key signing occur when the storage client uses the credential, not when it is registered.

Member	Type / required for use	Behavior
client_email	nonempty string / required	Service-account identity used when creating signed credentials.
private_key	nonempty string / required	Signing key in the provider-issued JSON format; it must parse and support signing.
private_key_id	string / optional	Key ID included when supplied; omission or an empty string leaves it unset.
token_uri	nonempty string / optional	Default https://oauth2.googleapis.com/token. Used when exchanging an assertion for an OAuth token.
universe_domain	nonempty string / optional	Default googleapis.com. Passed to the SDK’s service-account handling; use the value from the issued key.
project_id	nonempty string / optional	Retained by the SDK as project metadata; no value is inferred by this parser when omitted.

The service-account parser does not use type, client_id, auth_uri, auth_provider_x509_cert_url, or client_x509_cert_url to authenticate. Likewise, client_secret, refresh_token, and access_token do not turn this path into user or token authentication. Extra members are retained in the registered JSON object but do not replace the required service-account fields. No member-specific length cap is imposed by this parser; the query’s overall message-size limit still applies.

The Google Cloud C++ service-account parser interprets these fields. Provider authentication and bucket authorization must still succeed.

HTTPS origins

service: "https" in CreateCredential authorizes read-only access to remote objects. Every origin requires registration, including origins that need no authentication. Each resource is an exact origin such as https://media.example.com, with no path or trailing slash. An origin may belong to only one HTTPS credential. All origins in a credential share its key.

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": {
  "name": "public_media",
  "service": "https",
  "resources": ["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; HTTPS connections themselves cannot write to or delete the origin’s objects.

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 resource 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 the appropriate aws or gcp 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.

To rotate credentials, use UpdateCredential with a new key. To revoke one origin, remove that resource:

[{"UpdateCredential": {
  "name": "public_media",
  "remove_resources": ["https://media.example.com"]
}}]

Use RemoveCredential to revoke the whole credential. The server looks up the current origin authorization on subsequent reads, so an existing connection does not preserve revoked access. A fetch already in progress can complete with its captured credential; revocation does not erase objects previously copied into the database.