An identity your agent
can create itself.

Register, store the key, discover access

POST /v0/agent/register accepts an agent username and requires a strong, private Idempotency-Key. The response supplies a Free workspace, its default project and inbox, and a limited bootstrap API key. The agent can receive and read email and create drafts immediately. Sending email, creating API keys and allocating paid resources are not enabled by this key.

set -eu
umask 077
# Keep retry credentials outside source control.
LUPIN_STATE="$HOME/.local/state/lupin/research-agent"
mkdir -p "$LUPIN_STATE"
chmod 700 "$LUPIN_STATE"
test -s "$LUPIN_STATE/registration-key" || openssl rand -hex 32 > "$LUPIN_STATE/registration-key"
export LUPIN_REGISTRATION_KEY="$(cat "$LUPIN_STATE/registration-key")"

curl --fail-with-body \
  https://api.lupin.sh/v0/agent/register \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $LUPIN_REGISTRATION_KEY" \
  --data '{"username":"research-agent"}' \
  --output "$LUPIN_STATE/registration.pending.json"

# Preserve the previous response until a successful reply is validated.
jq -e '.api_key and .organization_id and .inbox_id' "$LUPIN_STATE/registration.pending.json" > /dev/null
mv "$LUPIN_STATE/registration.pending.json" "$LUPIN_STATE/registration.json"
export LUPIN_API_KEY="$(jq -er '.api_key' "$LUPIN_STATE/registration.json")"

curl --fail-with-body https://api.lupin.sh/v0/capabilities \
  --header "Authorization: Bearer $LUPIN_API_KEY"

This example needs HTTPS, OpenSSL and jq. It does not depend on a published Lupin SDK package or an interactive browser session.

Keep the registration identity private

1. Create one attempt identity

   Generate an unguessable key and preserve it before making the request. Reuse the same key and username when retrying that registration.

2. Store credentials safely

   The response includes an API key. Store it in a private file or secret store. Do not commit either credential file or include the key, raw response or registration key in public logs or messages.

3. Inspect before acting

   Use the workspace key to read capabilities, current limits and operation schemas. Keep paid and externally visible actions inside the applicable permission and consent boundaries.

Registration gives an identity, not someone else’s permissions

A new identity can receive messages, read its own workspace and prepare drafts. It does not automatically authorize an email recipient, a phone destination, a charge or an account in Google, Slack or another app. These operations retain their own verification, permissions and spending controls.

A verified human can claim the agent workspace in the console using its bootstrap key. Keep the key out of the URL. Claiming creates a console owner; the original bootstrap key remains limited. The owner can then manage access through the workspace’s normal permission and billing settings.

References an agent can read directly

• Agent skill: the registration flow and operational boundaries.
• LLM reference: links to public product and API documentation.
• OpenAPI specification: request schemas and available operations.
• Product guides and pricing: capabilities, setup requirements and usage boundaries.

Common questions