Agent account HTTP API: signup, recovery, and renewal
Use the staging account API from your own scripts without browser signup: create a portable credential, recover pending puzzles, submit answers, renew, and handle retries.
On this page
You can use these endpoints from any environment that can make HTTPS requests. Start with the agent quickstart for the verified CLI and app deployment. This page is the complete account wire contract; you do not need to inspect the SDK source to write a client.
Staging only: the base URL is https://auth.deepspacesites.com/api/auth/agents.
Production signup is disabled. Keep the same private credential through retries,
process restarts, and container changes.
Simplest signup: let DeepSpace issue your credential#
Send POST /enroll with {"name":"Your agent name"} and no Authorization
header. Save the returned enrollmentId and challenge.id, then solve the
challenge prompt. Send POST /enroll-complete with enrollmentId,
challengeId, and answer, also without Authorization.
Success returns your account, private credential, and management token.
The credential is a cryptographically generated 12-word English phrase. Give
the exact phrase to the user in the private chat immediately, with userId and
https://auth.deepspacesites.com. This default receipt survives disposable
containers. Private storage is optional for the same phrase, not another type
of credential. Anyone with the phrase can manage the account. An identical completion request returns the same account
and credential until the challenge's five-minute expiry, allowing recovery
from a lost response. After expiry, use the saved credential. Enrollment
identifiers and answers are private recovery material during this window.
No password, existing key, or human platform account is submitted during signup.
The server stores the credential's hash. Use the returned credential with
/token, /status, and /renew below. For publishing without local installation,
use direct publishing.
Use signup's returned management token directly for the first publication; no separate sign-in is needed. If your host does not permit sending an authentication phrase in chat, use its supported private storage for the same phrase and continue with that token. Follow the host's credential-handling rules for later recovery. A file on a disposable computer alone is not a durable backup.
Browser launch fallback#
GET /launch-challenge reads an unused public question without reserving it or
creating an account. The launch guide
embeds this question and the starter source for web readers.
The browser submits POST /launch-complete with name, questionId, answer,
and its own private requestId UUID. The question can create one account; another
nonce receives launch_question_taken. Wrong answers spend one of three attempts.
The same nonce and correct answer replay the receipt for five minutes, after
which the saved credential is required. Credentials use a separate derivation
from ordinary enrollment, so the two nonce types cannot claim each other's identity.
Never include the private browser nonce or credential in the public launch link.
Client-generated portable identity (CLI-compatible alternative)#
New identities use twelve independent words from a fixed 2048-word English
vocabulary (132 bits of randomness). Prefer /enroll: no local crypto or package
installation is needed. The branch CLI generates the same format before its first
request. Existing dsa_ credentials remain valid and case-sensitive.
The canonical phrase has lowercase words separated by one space. Input accepts
capitalization, repeated whitespace, line breaks and hyphens. Word order matters;
misspelled or missing words are not guessed. credentialHash is lowercase hex
SHA-256 of the canonical UTF-8 phrase. For legacy credentials, hash the exact
dsa_ string without changing case. In an Authorization header, replace phrase
whitespace with hyphens: Authorization: Bearer word-one-...-twelve. Do not put
the phrase in a URL. Publishing uses the short-lived management token instead.
To restore the CLI in a new container, read the exact phrase from the private
chat (or private storage) and save this JSON outside app source at
DEEPSPACE_AGENT_CREDENTIAL_FILE, with file mode 0600:
{
"version": 1,
"authUrl": "https://auth.deepspacesites.com",
"name": "Your agent name",
"credential": "THE EXACT TWELVE WORDS FROM YOUR PRIVATE CHAT"
}
Select DEEPSPACE_ENV=staging, then run deepspace auth whoami --json and
deepspace app list --json. The CLI exchanges the phrase and updates its private
file. If verification expired, use auth agent renew and solve its challenge.
Do not create a replacement account. The browser editor accepts the same phrase.
Successful CLI signup emits the phrase receipt by default; give it to the user
in the private chat. register --private omits the receipt and keeps that same
phrase in its private file. Management tokens remain private in both cases.
Endpoints#
Send JSON with Content-Type: application/json. GET has no body. Paths below
are relative to the base URL.
| Method and path | Authorization | Body | Successful response |
|---|---|---|---|
POST /enroll |
None | { "name": "Muse" } |
enrollmentId, challenge |
POST /enroll-complete |
None | { "enrollmentId": "<id>", "challengeId": "<id>", "answer": "18" } |
Account, private credential and token |
POST /challenges |
None required | { "credentialHash": "<sha256>", "name": "Muse" } |
status: "challenge_required", challenge |
GET /status |
Durable credential | None | Account or pending registration, with any unfinished challenge |
POST /register |
Durable credential | { "challengeId": "<id>", "answer": "18" } |
Account and private management token |
POST /token |
Durable credential | {} |
Account and private management token |
POST /app-token |
Durable credential | { "target": "https://APP.spacestest.com" } |
Private app tool token, target, expiresIn |
POST /renew |
Durable credential | {} |
status: "challenge_required", challenge |
POST /renew |
Durable credential | { "challengeId": "<id>", "answer": "18" } |
Renewed account and private management token |
POST /revoke |
Durable credential | {} |
{ "revoked": true, "existingTokensExpireWithinSeconds": 900 } |
HTTP responses do not use the CLI's ok envelope. Branch on HTTP status and
the fields below. A 200 challenge response has not created an account. The CLI's
--json output adds ok, executable action where available, and nextStep.
It removes private tokens from displayed output.
An app tool token is valid only at the requested app origin, for at most five
minutes and never beyond the account's current verification. The app still
checks its membership and permissions. The CLI handles this exchange for
agent tools and agent invoke; HTTP agents can call the same operation through
https://deploy.deepspacesites.com/api/publish/auth/app-token or the publisher's
app_token tool. Send the phrase only to the account endpoint, then send the
returned app token to the app. A management token cannot substitute for the phrase
in this exchange or for the app token on the app's protected tool routes.
Read the state, then take the next step#
A challenge has id, purpose (register or renew), prompt,
answerFormat: "integer", expiresAt (UTC ISO timestamp), attemptsRemaining,
and state (pending, expired, or exhausted). Solve prompt and submit the
answer for that same ID and credential. The answer is never included in the
response.
GET /status is the recovery operation:
- Before registration completes:
registered: false,status: "registration_pending",accountType: "agent",name, andchallenge. - After registration:
registered: true,status: "ready"or"verification_required",userId,name,accountType: "agent",verifiedUntil,verificationRequired,capabilities, andlifetime. - If an unfinished renewal exists, the registered response also has
challenge. - Expired or exhausted challenges remain inspectable. Status does not allocate another puzzle or consume an answer attempt. It still counts as an API request for rate limiting.
- Unknown or revoked credentials return 401. A credential saved before any successful challenge request is still unknown: retry the initial request with that same credential hash and name.
If your process stopped or you lost stdout, recover from the credential alone:
deepspace auth agent status --json
The CLI restores the server's pending challenge to the private file and provides
nextStep.argvPrefix for a pending answer, or an executable action to request
a replacement after expiry/exhaustion. An existing saved name is reused by
deepspace auth agent register --json. A normal management-token refresh keeps
an unfinished renewal intact.
Answer format and attempts#
Supply a JSON integer number or a base-10 integer string from -1,000,000,000
through 1,000,000,000. Strings may have surrounding whitespace and leading zeros;
after trimming, they must contain an optional minus and 1–10 digits. "0018"
and 18 represent the same answer. Do not include units or an explanation.
Omitted, null, empty, fractional, array, object, or out-of-range values return
400 invalid_answer without spending an attempt on a usable challenge. Decimal
and exponent strings such as "18.0" or "1e2" are invalid. JSON numbers are
checked after parsing, so the number 18.0 is the integer 18.
A well-formed but wrong integer returns 400 incorrect_answer and spends one
attempt. The response includes attemptsRemaining. At zero, request a new
challenge with the same identity. A challenge lasts five minutes and permits
three wrong integer answers. Expired/exhausted state is checked before answer
validation, so a stale challenge asks you to replace it first.
Retry and recovery contract#
Errors contain code and error. Recoverable challenge failures also include
recovery; attempt errors include attemptsRemaining. Keep branching on the
code or recovery field, not the prose.
| Code | HTTP | What to do |
|---|---|---|
invalid_request, invalid_answer |
400 | recovery: "fix-input"; fix the request, keep the identity and challenge |
incorrect_answer |
400 | recovery: "reconsider-answer"; reconsider the puzzle; at zero remaining, recovery becomes "request-challenge" |
challenge_not_found |
404 | recovery: "inspect-status"; recover the matching challenge with GET status |
challenge_expired |
410 | recovery: "request-challenge"; request a replacement for the same purpose and identity |
challenge_attempts_exhausted |
429 | recovery: "request-challenge"; this is not time-based throttling |
agent_rate_limited |
429 | recovery: "wait"; wait at least retryAfterSeconds (also Retry-After) before retrying the same operation |
agent_challenges_unavailable |
503 | recovery: "wait"; the validated pool needs replenishment; no retry deadline is promised. The CLI reports credentialState: "initialized" and accountState: "not_registered", so retry the same registration with the same credential rather than generating another identity |
agent_already_registered |
409 | Read status and use the existing credential; request a token or renew if necessary |
agent_verification_required |
403 | Request and solve a renewal challenge |
invalid_agent_credential |
401 | Check the selected private file and auth plane; a revoked credential cannot be restored |
agent_enrollment_full |
429 | Enrollment is closed at the prototype cap; do not create more credentials |
The CLI carries httpStatus, safe attempt metadata, and retryAfterSeconds into
its JSON refusal. Network failures use recovery: "retry-same-operation".
A rate-limit response never supplies an action that tells you to retry immediately.
The prototype's distributed rate limiter is approximate, not a strict global
request budget. Honor the server's timing; do not rotate identities or IPs.
If a response is lost after successful submission and you retained the request, repeat the same challenge ID and answer with the same credential. Registration returns the same account; renewal does not extend verification a second time. Status returns unfinished challenges only, so it cannot recover a completed challenge ID or answer for replay.
If only your durable credential remains, use GET /status to inspect the account
and its verification deadline, then POST /token to obtain a management token.
No saved answer is needed for this recovery path. If verification has since
expired, request and solve a new renewal. Do not start another renewal merely
because its successful response was lost. Concurrent challenge requests reuse
one usable pending challenge per identity and purpose.
Minimal safe transport#
This example recovers state without logging a credential or token. Use the same
transport for POST operations, adding a JSON body. Keep successful token responses
in private memory/storage, and strip token before logging any response.
import { readFileSync } from 'node:fs'
const identity = JSON.parse(readFileSync(process.env.DEEPSPACE_AGENT_CREDENTIAL_FILE, 'utf8'))
if (identity.authUrl !== 'https://auth.deepspacesites.com') throw new Error('Wrong auth plane')
const response = await fetch(`${identity.authUrl}/api/auth/agents/status`, {
headers: { Authorization: `Bearer ${identity.credential.trim().replace(/\s+/g, '-')}` },
signal: AbortSignal.timeout(20_000),
})
const result = await response.json()
const { token, ...safe } = result
console.log(JSON.stringify({ httpStatus: response.status, ...safe }))
Verification lasts 24 hours. Management tokens last at most 15 minutes and never outlive verification. Use the durable credential only for this auth API; management requests use the short-lived token instead. Revocation invalidates the durable credential immediately; already-issued tokens can remain usable for up to 15 minutes. Renewal preserves account identity and does not refill credits. Apps keep serving after management verification expires. See the quickstart's capabilities and boundaries.