Fileaify agent API — Access — Requesting access

Part of the Fileaify agent protocol. Start page and index: /agent. Everything in one document: /agent/full.

Request additional access

Pairing never grants a secret. Capabilities are separate: project.read, documents.write, resources.read, secrets.use and secrets.export. Secret export requires an explicit binding grant; resource visibility alone cannot reveal it.

Secret export is off by default. It works only when the owner enabled it in the account, in the workspace settings and in the project; otherwise any secrets.export request or reveal returns 403 secret_export_disabled. Do not retry: tell the user which option to enable. Prefer secrets.use (broker or executor env), which never gives you the value. If you must hold a value, keep it out of your conversation: write a small local routine that calls the reveal endpoint with your token, stores the answer in a private file and lets your procedures read that file without printing it.

POST /api/v1/projects/{project_id}/access-requests accepts:

{"capability":"resources.read","reason":"Why this task needs service references"}

For secret export, use capability:"secrets.export" and the specific binding_id. Permissions have no use counter and you do not propose a duration: the human who accepts chooses it (1 hour, 5 hours, 1 day or 1 week; 1 hour by default), so ask again after it ends. Any hours or max_uses you send is ignored. The project and binding must belong to the token's organization. Do not guess identifiers to probe inaccessible projects; obtain the authorized project context from the user.

GET /api/v1/access-requests returns your requests. Only an organization owner/administrator may approve them; the server generates the grant's documentary reference and rationale. A document mentioning a right does not create it. Missing or stale access documentation is a warning, never an authorization fallback.

GET /api/v1/projects/{project_id}/resources lists authorized service usages and bindings. Once a specific export grant is active, POST /api/v1/projects/{project_id}/bindings/{binding_id}/reveal with {} returns the authorized value and consumes an allowed use. For an imported file, encoding: "base64", filename and size accompany value; decode it only into private tool storage. ?download=1 on that same POST returns the binary attachment with the same authorization and single-use consumption. Files cannot be used as HTTP authentication headers through the broker. Never log, document or forward that value to an unrelated destination. Do not automatically retry an uncertain secret delivery: an allowed use may already have been consumed. Revoking a grant blocks future delivery but cannot retract a value already exported.

See which keys exist: vault references

GET /api/v1/projects/{project_id}/references (MCP read_references) is readable with project.read. It lists the vault references of the project (vault://brevo/key-sitefait), the service and provider, the kind (secret or file), the usage of the key in this project, its state and the binding_id to quote in an access request. It never returns values, versions or endpoints. Use it to decide which key to ask for, then request secrets.use or secrets.export for that binding_id (see above). GET /readiness returns the same references with can_use and can_export. The detail of services, connections and destinations still requires resources.read. In project documents, write a reference only when it is a real one: every vault://… string is read as a reference and an unlinked one raises an attention point. For the rare illustrative example, put a backslash right before it (\vault://service/key): it is then plain text.

Request a missing project binding

GET /api/v1/projects/{project_id}/readiness reports your effective project capabilities, visible bindings with their purpose, permitted secret operations, pending requests, plan restrictions and document locks. It never reveals secret values or secrets belonging to other projects.

If a required key is not linked, submit POST /api/v1/projects/{project_id}/binding-requests with {"reference":"vault://stripe/my-key","purpose":"Test subscription billing","reason":"Required to implement this project's billing"}. You need project.read. The request goes to organization owners/administrators in the web/PWA inbox. Its response does not confirm whether the key exists elsewhere. A human may create the missing key through the vault, then approve the request. An ambiguous reference must be corrected; the server never guesses.

Approval links the existing service and secret to this project, records the purpose in the access register and returns a binding_id through GET /api/v1/access-requests. It grants no secret use or export. Then request the required capability separately using the access-request API above. Request approval expires after 24 hours; the secret-use request has its own duration and usage count. Never ask the user to paste a secret into the conversation.

Use a credential without requesting its export

An organization administrator can enable HTTPS access on a connection: an exact URL, authentication header/format and allowed methods. This is disabled by default. An explicit secrets.use grant on the binding is separate from secrets.export; request it through the same access-request API with a reason, duration and usage limit.

POST /api/v1/projects/{project_id}/bindings/{binding_id}/request accepts {"method":"GET","body":""}. body is an optional JSON text string (maximum 32,768 characters). The agent cannot change the destination or headers. Fileaify injects the binding's current credential, verifies TLS against the configured hostname and pins a public IPv4 address. Private/special addresses, non-HTTPS destinations and redirects are refused. Only configured methods are allowed. Responses are limited to 64 KiB and returned as {status,body}; obvious credential echoes are redacted. Never treat this redaction as a guarantee that an untrusted provider cannot disclose a credential: administrators must trust the exact destination they configure.

The binding's use is consumed before transmission; failure or an ambiguous response also consumes it. Do not retry automatically, especially writes. The initial instance limits broker calls to 100 per day. This does not offer arbitrary URL fetching or SSH execution. Use an explicit, separately approved export grant if the operational tool requires a local credential.