Using the Secrets Vault from an agent
This article is for you if you build or run an agent that needs credentials from the Secrets Vault while it executes a flow. For what the Vault is, why Floxar cannot read what it stores, and how an admin sets it up, read The Secrets Vault first.
What your agent needs
- A registered agent. The agent signs in to Floxar with its own client credentials, as described in Registering an agent. The Vault identifies the agent by that identity.
- A token that names a level. Secrets are kept at a level of your account: the account itself, or one of its organizations or groups. Each token your agent presents to the Vault names one level and reads that level's secrets only (see "A token for the Vault" below).
- A grant for each secret. An account admin grants your agent access to each secret it will use, at the level where the secret is kept, bound to a specific recipient key. Grants are per secret and deny by default: the agent's role does not open any secret on its own.
- The recipient private key file. The admin gives your agent the private key file that matches the key in its grants. Treat it like any other production secret. Floxar never receives it.
A token for the Vault
Your agent requests its Vault token from Floxar's token issuer the way it requests any other, with one more form field, scope_id, and without resource:
curl -X POST https://tokens.floxar.com/oauth2/token \n -H "Content-Type: application/x-www-form-urlencoded" \n -d "grant_type=client_credentials" \n -d "client_id=$FLOXAR_CLIENT_ID" \n -d "client_secret=$FLOXAR_CLIENT_SECRET" \n -d "scope_id=root"
That request is for the account level. For an organization or group, send its id in place of root: scope_id=<scope_id>.
scope_id in the request | What the Vault does with the token |
|---|---|
| The id of an organization or group | Reads the secrets kept at that level |
The word root, in lower case | Reads the secrets kept at the account level |
| Not sent | Refuses the token with 401 |
Anything else: an empty value, ROOT in upper case, a malformed id, the field sent twice | No token is issued: the token endpoint answers 400 invalid_request with the description scope_id must be a scope id (a UUID) or the word root |
- Ask for the level whose secrets the work needs. For a step of a trail, that is the trail's level: its
scope_id, orrootfor a trail at the account level. - One token per level. A token reads one level. An agent that works at several levels requests one token for each, and never uses a secret read at one level for work at another.
- Naming a level grants nothing. The token endpoint checks only the form of the value. A level where your agent holds no grant, or an id that is not a level of your account, has nothing for it: the Vault answers 403.
- The request decides, nothing else. Your agent's role, its organization and group assignments and the level it is administered from play no part in which level a token reaches.
- A token without
scope_idis not a Vault token. It still works for Floxar's REST API, and a token requested withresourcestill works for MCP, so an agent that never reads secrets changes nothing. Neither is accepted by the Vault. - A refused
scope_idis a fault in the request. Correct the value; the same request will be refused again.
This field works with any HTTP client. If your agent obtains its tokens through a client library, check that the library sends scope_id on the token request; one that does not obtains tokens the Vault refuses.
How a secret is resolved
- A step in the flow carries a credential reference that names a handle, such as a CRM key, and says what the credential is for.
- Your agent authenticates with a token that names the level where the secret is kept and asks the Vault's agent API, at resolve.vault.floxar.com, to resolve that handle.
- The Vault looks the handle up at the token's level, checks that your agent holds an active, unexpired grant for the current version of the secret, applies your account's rate limit, which all of the account's agents share, and returns the encrypted value with Floxar's half of the key and your key's sealed half.
- Your agent opens the sealed half with its private key, combines the two halves, and decrypts the value in memory. It uses the value for the call the step needs and never writes it into step data, trail notes or flow content.
The Vault releases only encrypted material and Floxar's half of the key, so the value is only ever readable on your side.
Beta. Agent limits, including the Vault's rate limit for your account's agents, are in beta. Floxar may modify these limits at any time.
When the Vault refuses
- 401
invalid_token: the token is the problem. It is missing, expired, was requested withresource(an MCP token), or was requested withoutscope_id. Request a token that names the level, once. A grant does not help here, and the answer is the same whatever the handle. - 403: the token is accepted, and the secret is not released.
forbiddencovers every case where your agent has no usable grant at the token's level: the handle does not exist there, the secret was never granted to your agent or to the key it holds, or the grant is inactive or has expired. The Vault does not say which. Check that the token names the level where the secret is kept, then ask an account admin to check the grant. When your agent does hold an active grant, 403expiredmeans the secret's current version has expired, and 403revokedmeans the secret was revoked. A new token changes none of these. - 429
rate_limited: your account's agents together have reached the Vault's rate limit. Wait, then try again.
Caching and rotation
Cache each Vault token for its lifetime, keyed by the level it names: the account level and each organization or group are separate tokens, and separate again from the tokens your agent holds for MCP and for the REST API without a level. Every one of them is a token request against your account's allowance, so request each once and reuse it; see Registering an agent.
Your agent may cache a resolved value for a short, bounded time to avoid resolving on every step. Key that cache by level and handle: the same handle can name different secrets at two levels, and a value read at one level must never be served to work at another. When an admin rotates a secret, the next resolve returns the new version; a cached copy of the old version lasts until its cache time runs out.
When access is removed
Removing a grant or revoking a secret stops future resolves at once. It cannot recall a value your agent has already decrypted or cached. If a credential may have leaked, the only complete fix is to rotate it in the system it belongs to.
Auditing
Every resolve is recorded in the secret's access log with the agent, the time and the outcome, including refusals. Admins can review the log from the Vault at any time.
Last reviewed: 2026-11-10