POST Register or retrieve a machine account

/api/v1/auth/machine/register

The version-2 Ed25519 signature binds the challenge and both legal-document versions and acknowledgements. Only a SHA-256 credential hash is stored. A retry needs a fresh challenge and the same locally persisted credential.

On this page

Access and permissions

No account sign-in is required. Any listed browser-origin checks and rate limits still apply.

Parameters and headers

No path, query or additional request-header parameters.

Request body

Field	Type and limits	Required	Meaning
$	object; {"additionalProperties":false}	Yes	—
$.challenge_id	string; {"format":"uuid"}	Yes	UUID of the challenge issued to this browser or machine request.
$.credential_hash	string; {"maxLength":64,"minLength":64,"pattern":"^[0-9a-f]{64}$"}	Yes	Lowercase SHA-256 of the complete persisted mbm_ management credential. Never submit the credential secret as this hash.
$.credential_prefix	string; {"maxLength":12,"minLength":12,"pattern":"^[0-9a-f]{12}$"}	Yes	—
$.legal_acceptance	LegalAcceptance	Yes	—
$.legal_acceptance.privacy_acknowledged	boolean; {"const":true}	Yes	Must be true when acknowledgement of privacy information is required.
$.legal_acceptance.privacy_version	string; {"pattern":"^[0-9a-f]{64}$"}	Yes	SHA-256 version returned for the currently published privacy text.
$.legal_acceptance.terms_accepted	boolean; {"const":true}	Yes	Must be true when legal acceptance is required.
$.legal_acceptance.terms_version	string; {"pattern":"^[0-9a-f]{64}$"}	Yes	SHA-256 version returned for the currently published terms. Retrieve the current text before accepting.
$.public_key	string; {"maxLength":43,"minLength":43,"pattern":"^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$"}	Yes	Ed25519 public key: exactly 32 bytes, canonical unpadded base64url.
$.signature	string; {"maxLength":86,"minLength":86,"pattern":"^[A-Za-z0-9_-]{85}[AQgw]$"}	Yes	Ed25519 signature: exactly 64 bytes, canonical unpadded base64url. Sign the documented challenge message with the matching private key.

Responses

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/json

Field	Type and limits	Required	Meaning
$	object	Yes	—
$.account_id	string	Yes	UUID of the owning or acting account, as specified by this operation.
$.status	string	Yes	—

{
  "account_id": "demo",
  "status": "demo"
}

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/json

Field	Type and limits	Required	Meaning
$	object	Yes	—
$.account_id	string	Yes	UUID of the owning or acting account, as specified by this operation.
$.status	string	Yes	—

{
  "account_id": "demo",
  "status": "demo"
}

Stable error codes
invalid_peer

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

Field	Type and limits	Required	Meaning
$	Problem	Yes	—
$.code	string	Yes	Stable machine-readable error code
$.detail	string	Yes	Short localized explanation without internal error details
$.instance	string	Yes	Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.message	string	Yes	Temporarily identical to detail for existing clients
$.message_key	string	Yes	Stable translation key for changing the displayed language without another request
$.message_params	object; {"additionalProperties":true}	Yes	Named, safely rendered message parameters; never arbitrary HTML
$.request_id	string; {"pattern":"^[0-9a-f]{32}$"}	Yes	Server-generated diagnostic identifier. It contains no login token or credential.
$.status	integer; {"maximum":599,"minimum":400}	Yes	—
$.title	string	Yes	Localized HTTP status title
$.type	string; {"const":"about:blank"}	Yes	—

{
  "code": "demo",
  "detail": "Demo error detail; inspect the documented code.",
  "instance": "demo",
  "message": "Demo error detail; inspect the documented code.",
  "message_key": "errors.requestFailed",
  "message_params": {},
  "request_id": "00000000000000000000000000000000",
  "status": 400,
  "title": "Demo error",
  "type": "about:blank"
}

Stable error codes
account_unavailable

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

Field	Type and limits	Required	Meaning
$	Problem	Yes	—
$.code	string	Yes	Stable machine-readable error code
$.detail	string	Yes	Short localized explanation without internal error details
$.instance	string	Yes	Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.message	string	Yes	Temporarily identical to detail for existing clients
$.message_key	string	Yes	Stable translation key for changing the displayed language without another request
$.message_params	object; {"additionalProperties":true}	Yes	Named, safely rendered message parameters; never arbitrary HTML
$.request_id	string; {"pattern":"^[0-9a-f]{32}$"}	Yes	Server-generated diagnostic identifier. It contains no login token or credential.
$.status	integer; {"maximum":599,"minimum":400}	Yes	—
$.title	string	Yes	Localized HTTP status title
$.type	string; {"const":"about:blank"}	Yes	—

{
  "code": "demo",
  "detail": "Demo error detail; inspect the documented code.",
  "instance": "demo",
  "message": "Demo error detail; inspect the documented code.",
  "message_key": "errors.requestFailed",
  "message_params": {},
  "request_id": "00000000000000000000000000000000",
  "status": 403,
  "title": "Demo error",
  "type": "about:blank"
}

Stable error codes
credential_changed

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

Field	Type and limits	Required	Meaning
$	Problem	Yes	—
$.code	string	Yes	Stable machine-readable error code
$.detail	string	Yes	Short localized explanation without internal error details
$.instance	string	Yes	Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.message	string	Yes	Temporarily identical to detail for existing clients
$.message_key	string	Yes	Stable translation key for changing the displayed language without another request
$.message_params	object; {"additionalProperties":true}	Yes	Named, safely rendered message parameters; never arbitrary HTML
$.request_id	string; {"pattern":"^[0-9a-f]{32}$"}	Yes	Server-generated diagnostic identifier. It contains no login token or credential.
$.status	integer; {"maximum":599,"minimum":400}	Yes	—
$.title	string	Yes	Localized HTTP status title
$.type	string; {"const":"about:blank"}	Yes	—

{
  "code": "demo",
  "detail": "Demo error detail; inspect the documented code.",
  "instance": "demo",
  "message": "Demo error detail; inspect the documented code.",
  "message_key": "errors.requestFailed",
  "message_params": {},
  "request_id": "00000000000000000000000000000000",
  "status": 409,
  "title": "Demo error",
  "type": "about:blank"
}

Stable error codes
invalid_challenge
invalid_input

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

Field	Type and limits	Required	Meaning
$	Problem	Yes	—
$.code	string	Yes	Stable machine-readable error code
$.detail	string	Yes	Short localized explanation without internal error details
$.instance	string	Yes	Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.message	string	Yes	Temporarily identical to detail for existing clients
$.message_key	string	Yes	Stable translation key for changing the displayed language without another request
$.message_params	object; {"additionalProperties":true}	Yes	Named, safely rendered message parameters; never arbitrary HTML
$.request_id	string; {"pattern":"^[0-9a-f]{32}$"}	Yes	Server-generated diagnostic identifier. It contains no login token or credential.
$.status	integer; {"maximum":599,"minimum":400}	Yes	—
$.title	string	Yes	Localized HTTP status title
$.type	string; {"const":"about:blank"}	Yes	—

{
  "code": "demo",
  "detail": "Demo error detail; inspect the documented code.",
  "instance": "demo",
  "message": "Demo error detail; inspect the documented code.",
  "message_key": "errors.requestFailed",
  "message_params": {},
  "request_id": "00000000000000000000000000000000",
  "status": 422,
  "title": "Demo error",
  "type": "about:blank"
}

Stable error codes
registration_capacity

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Retry-After	string; {"pattern":"^[0-9]+$"}	Seconds before retry. Preserve supported idempotency identifiers and respect the operation’s mutation semantics.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

Field	Type and limits	Required	Meaning
$	Problem	Yes	—
$.code	string	Yes	Stable machine-readable error code
$.detail	string	Yes	Short localized explanation without internal error details
$.instance	string	Yes	Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.message	string	Yes	Temporarily identical to detail for existing clients
$.message_key	string	Yes	Stable translation key for changing the displayed language without another request
$.message_params	object; {"additionalProperties":true}	Yes	Named, safely rendered message parameters; never arbitrary HTML
$.request_id	string; {"pattern":"^[0-9a-f]{32}$"}	Yes	Server-generated diagnostic identifier. It contains no login token or credential.
$.status	integer; {"maximum":599,"minimum":400}	Yes	—
$.title	string	Yes	Localized HTTP status title
$.type	string; {"const":"about:blank"}	Yes	—

{
  "code": "demo",
  "detail": "Demo error detail; inspect the documented code.",
  "instance": "demo",
  "message": "Demo error detail; inspect the documented code.",
  "message_key": "errors.requestFailed",
  "message_params": {},
  "request_id": "00000000000000000000000000000000",
  "status": 429,
  "title": "Demo error",
  "type": "about:blank"
}

Stable error codes
machine_registration_unavailable
unavailable

Header	Type and limits	Meaning
Cache-Control	string; {"pattern":"(?:^\|,\\s*)no-store(?:,\|$)"}	Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation.
Content-Language	string; {"enum":["en","de"]}	Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable.
Referrer-Policy	JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]}	The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters.
Retry-After	string; {"pattern":"^[0-9]+$"}	Seconds before retry. Preserve supported idempotency identifiers and respect the operation’s mutation semantics.
Vary	string	Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie.
X-Content-Type-Options	JSON; {"const":"nosniff"}	The browser must use the declared content type.
X-Frame-Options	JSON; {"const":"DENY"}	The response must not be embedded in a frame.
X-Request-ID	string	Server-generated request identifier. Include this when reporting an error; inbound values are not trusted.

application/problem+json

Field	Type and limits	Required	Meaning
$	Problem	Yes	—
$.code	string	Yes	Stable machine-readable error code
$.detail	string	Yes	Short localized explanation without internal error details
$.instance	string	Yes	Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.message	string	Yes	Temporarily identical to detail for existing clients
$.message_key	string	Yes	Stable translation key for changing the displayed language without another request
$.message_params	object; {"additionalProperties":true}	Yes	Named, safely rendered message parameters; never arbitrary HTML
$.request_id	string; {"pattern":"^[0-9a-f]{32}$"}	Yes	Server-generated diagnostic identifier. It contains no login token or credential.
$.status	integer; {"maximum":599,"minimum":400}	Yes	—
$.title	string	Yes	Localized HTTP status title
$.type	string; {"const":"about:blank"}	Yes	—

{
  "code": "demo",
  "detail": "Demo error detail; inspect the documented code.",
  "instance": "demo",
  "message": "Demo error detail; inspect the documented code.",
  "message_key": "errors.requestFailed",
  "message_params": {},
  "request_id": "00000000000000000000000000000000",
  "status": 503,
  "title": "Demo error",
  "type": "about:blank"
}

Retries and asynchronous work

This change does not have a general retry guarantee. If the response is unclear, read the affected resource before trying again. Follow Retry-After waiting times and request new sign-in or action codes when they expire.

Request examples

Replace demo IDs, timestamps and placeholders with your own values. For a retry, keep the same IDs, time and content. These examples do not run requests on this page.

Keep login links, codes, cookies and keys private. Do not print them in logs or share them in support requests.

curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary '{"challenge_id":"00000000-0000-4000-8000-000000000001","credential_hash":"0000000000000000000000000000000000000000000000000000000000000000","credential_prefix":"000000000000","legal_acceptance":{"privacy_acknowledged":true,"privacy_version":"0000000000000000000000000000000000000000000000000000000000000000","terms_accepted":true,"terms_version":"0000000000000000000000000000000000000000000000000000000000000000"},"public_key":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","signature":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}' \
  "https://metribeacon.com/api/v1/auth/machine/register"

import json
from pathlib import Path
from urllib.request import Request, HTTPRedirectHandler, build_opener
from urllib.error import HTTPError

headers = {}
headers["Content-Type"] = "application/json"
request = Request("https://metribeacon.com/api/v1/auth/machine/register", data="{\"challenge_id\":\"00000000-0000-4000-8000-000000000001\",\"credential_hash\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"credential_prefix\":\"000000000000\",\"legal_acceptance\":{\"privacy_acknowledged\":true,\"privacy_version\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"terms_accepted\":true,\"terms_version\":\"0000000000000000000000000000000000000000000000000000000000000000\"},\"public_key\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\",\"signature\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}".encode("utf-8"), headers=headers, method="POST")
class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, request, fp, code, message, headers, target):
        return None

opener = build_opener(NoRedirect())
try:
    with opener.open(request, timeout=10) as response:
        print(response.status)
except HTTPError as error:
    print(error.code)
    error.close()

import { readFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";

const headers = {};
headers["Content-Type"] = "application/json";
const response = await fetch("https://metribeacon.com/api/v1/auth/machine/register", {
  method: "POST", headers, redirect: "manual",
  signal: AbortSignal.timeout(10000), body: "{\"challenge_id\":\"00000000-0000-4000-8000-000000000001\",\"credential_hash\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"credential_prefix\":\"000000000000\",\"legal_acceptance\":{\"privacy_acknowledged\":true,\"privacy_version\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"terms_accepted\":true,\"terms_version\":\"0000000000000000000000000000000000000000000000000000000000000000\"},\"public_key\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\",\"signature\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}",
});
console.log(response.status);
await response.body?.cancel();

package main

import (
  "fmt"
  "net/http"
  "time"
  "strings"
)

func main() {
  request, err := http.NewRequest("POST", "https://metribeacon.com/api/v1/auth/machine/register", strings.NewReader("{\"challenge_id\":\"00000000-0000-4000-8000-000000000001\",\"credential_hash\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"credential_prefix\":\"000000000000\",\"legal_acceptance\":{\"privacy_acknowledged\":true,\"privacy_version\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"terms_accepted\":true,\"terms_version\":\"0000000000000000000000000000000000000000000000000000000000000000\"},\"public_key\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\",\"signature\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}"))
  if err != nil { panic("request failed; credentials and response omitted") }
  request.Header.Set("Content-Type", "application/json")
  client := &http.Client{Timeout: 10*time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
  response, err := client.Do(request)
  if err != nil { panic("request failed; credentials and response omitted") }
  defer response.Body.Close()
  fmt.Println(response.StatusCode)
}

HTTP API, OAuth and MCP
Find the user API endpoints, their permissions, fields, examples and response formats.
POST Request a one-time Ed25519 machine challenge
Requires the enabled registration/recovery capability for the requested purpose. Save the private Ed25519 recovery identity and proposed management credential locally before the request. The challenge binds purpose and public key and expires in five minutes.
POST Request email verification for a machine account
Requires account:write on a machine credential. The existing verified address and tier remain until confirmation. Replies are generic for addresses already in use.
POST Replace a machine management credential using recovery
Sign a fresh recover challenge with the existing recovery identity. Persist the replacement credential before requesting recovery. Repeating with a fresh challenge yields the same account and returns no secret.

Access and permissions

Parameters and headers

Request body

Responses

Retries and asynchronous work

Request examples

Related guides