Agents API reference

What is an agent identity in the API?

An agent identity is a named principal inside your organization. It has a name, a purpose written for people, a contact address, a list of policies and a status. A fax sent with one of its keys is recorded against the agent. The audit trail then says which agent acted, not only which organization.

Registering an agent does not let it send anything. POST /v1/agents writes the identity and answers with its id. The agent can call the API only after a key is minted for it. The read of one agent returns the identity with its keys and its budgets in one answer, so a dashboard needs one call per agent.

How does an agent get its key?

POST /v1/agents/{agent_id}/keys mints a key that belongs to the agent. The body can name a label, an environment, a number of days until it expires and a list of scopes. Leave the scopes out and the key is given the default agent set. The answer carries the secret once. Later reads show the prefix, the scopes and the dates, never the secret.

The scopes are bounded. The schema of the request says an agent key is never issued approval:decide, key:admin, policy:admin or agent:admin. A request that asks for one of them is refused. That boundary is why an agent can ask a person to approve a send and cannot approve its own request. The agents guide lists the full default set and the scopes that are never issued.

What happens when an agent is disabled?

PATCH /v1/agents/{agent_id} changes the name, the purpose, the contact address and the policy list. It also takes enabled. Sending false disables the agent and revokes each of its keys in the same call, so none of its keys outlives the identity.

Disabling is the fast way to stop one agent without touching the others. Keys of other agents and keys of the organization keep working.

Where do I see what an agent did?

GET /v1/agents/{agent_id}/activity returns the audit rows of one agent, a page at a time. It takes cursor and limit, and each page carries next_cursor while more rows remain. The rows hold metadata about each action. They never hold the content of a document.

Which scopes do these calls need?

Reading the list, one agent or its activity needs agent:read. Registering an agent, changing it and minting a key for it need agent:admin. Each operation below states its own scope on its credential line, read from the OpenAPI document.

Agent keys cannot run the admin calls of this group. A person does that from a signed-in session, or a key of the organization that holds agent:admin does it from a script. The list call returns every agent of the organization in the environment of the credential.

How do agents relate to policies and budgets?

An agent names its policies in policy_ids. A delegated policy says where the agent may send and how much, and the server evaluates it on each send. A budget is a spending cap. The read of an agent returns its budgets. The cap itself is created in the billing group with the agent's id.

The three together bound one agent. Its scopes say which calls it may make. The policy says which sends are allowed without a person. The budget says how much it may spend.

curl https://api.faxforagents.com/v1/agents \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/agents \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"example"}'

curl https://api.faxforagents.com/v1/agents/AGENT_ID \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/agents/AGENT_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.faxforagents.com/v1/agents/AGENT_ID/activity \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/agents/AGENT_ID/keys \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'