create_user
Create a user and its API key. Use type agent for an AI agent and person for a human that work can be assigned to. Each agent that should be told apart from the others needs its own user. The key is returned once, here; give it to the client, which sends it in the Authorization header.
- It
- Changes the plan, as one step that is stored whole or not at all, and then stores the key in the config file, which is a step of its own.
- Who may call it
- Admins only. It is not listed for anyone else.
- Version
- Takes no version: it is carried out on the plan as it is at that moment.
- Answers with
- The user and its API key.
- MCP tool
create_user- HTTP
POST /api/create-user- Command
vigile create-user
Input
| Field | Takes | What it is | |
|---|---|---|---|
username | string | required | Lowercase letters, digits, "-" and "_", starting with a letter; at most 32 characters. |
type | "person" | "agent" | required |
A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --username.
Example
The same call three ways, as admin. It was made on the demo plan the pictures of this site show. Over HTTP, vig_... stands for the key of admin; over MCP, the client is set up with that key.
Command line
vigile create-user --username agent3 --type agentHTTP
curl -s http://127.0.0.1:8700/api/create-user \
-H 'content-type: application/json' \
-H 'Authorization: Bearer vig_...' \
-d '{"username":"agent3","type":"agent"}'MCP tool call
{
"name": "create_user",
"arguments": { "username": "agent3", "type": "agent" }
}The answer
{
"user": {
"kind": "user",
"id": "USER-005",
"username": "agent3",
"type": "agent",
"built_in": false,
"version": 1
},
"api_key": "vig_…"
}
This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.
A call that is refused
vigile create-user --username agent2 --type agent
{
"error": {
"code": "rule_violation",
"message": "The username agent2 is already used.",
"rule": "username_taken",
"actions": ["Choose a different username."]
}
}
What it answers
The new user, and its api_key. The key is shown once, here. Give it to the client, which sends it as Authorization: Bearer <key>. A warning beside it means the key works but could not be confirmed to last; issue another with reset_user_key once the cause is put right.
On the page the key is shown as vig_…; a real one is longer.
Rules
- A username has lowercase letters, digits, "-" and "_", starts with a letter, has at most 32 characters, and cannot read like an ID, such as
user-7. - A username that is in use cannot be taken, also not one of a deleted user: restore that user, or choose another name.
- The type is
agentorperson. There is one admin, which is built in. - The key applies at once.
On the command line, vigile user add calls this and prints the settings for the agent's MCP configuration as well.
Errors
forbidden: the caller is not an admin.invalid_input: the username cannot be one, or the type is none of the two.rule_violationwithusername_taken.internal, "User … was created, but its API key could not be stored": the user is there and cannot connect yet. Do not create it again: issue its key withreset_user_keyonce the cause, which is in the service's log, is put right.