Signup

GET /api/v1/signup/resolve

Resolve a signup-link token into claim context (unauthenticated)

Verify a signup rid token and return the claim context.

200 — valid token: {name, country_code, brand_id, identifier_masked, maps_byok_key_or_null}.
401 — token expired, signature invalid, or malformed (detail masked).
410 — token minted before B.1 (no brand_id); ask for a fresh link.

Parameters

token string query required

Responses

200Successful Response
422Validation Error

GET /api/v1/signup/resolve

curl -X GET 'https://api.example.com/api/v1/signup/resolve' \
  -H 'Authorization: Bearer '

import httpx

resp = httpx.get(
    "https://api.example.com/api/v1/signup/resolve",
    headers={"Authorization": "Bearer "},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/signup/resolve", {
  method: "GET",
  headers: { "Authorization": "Bearer " }
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.example.com/api/v1/signup/resolve", nil)
	req.Header.Set("Authorization", "Bearer ")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

GET /api/v1/signup/check-name

Check whether a VayaPin name is available (unauthenticated, token-authz)

Verify a signup rid token and report whether name is available.

200 — {is_available, suggestions}: free name → empty suggestions; taken name → up to 10 alternatives the cs-api proposed.
401 — token expired, signature invalid, or malformed (detail masked).
410 — token minted before B.1 (no country_code); ask for a fresh link.
429 — per-token rate limit exceeded (5/s or 60/min).
502 — cs-api returned an uninterpretable availability body (our bug).
500 — cs-api credential misconfigured (our bug).
503 — cs-api temporarily unavailable.

Parameters

token string query required

name string query required

Responses

200Successful Response
422Validation Error

GET /api/v1/signup/check-name

curl -X GET 'https://api.example.com/api/v1/signup/check-name' \
  -H 'Authorization: Bearer '

import httpx

resp = httpx.get(
    "https://api.example.com/api/v1/signup/check-name",
    headers={"Authorization": "Bearer "},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/signup/check-name", {
  method: "GET",
  headers: { "Authorization": "Bearer " }
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.example.com/api/v1/signup/check-name", nil)
	req.Header.Set("Authorization", "Bearer ")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

POST /api/v1/signup/complete

Finalise a consumer claim — write the pin and notify the agent

Write the claimed pin to cs-api and fire pin_created.

Anonymous by design (2026-06-22 rescope): the consumer reaches this with no better-auth session, so session is None on the V1 path. The signup token — not a login — is the claim authorization.

202 — accepted: {vayapin_id, state} (done | creating).
401 — token expired / invalid (the signup token, not a session).
404 — no reservation for this token (confirm-pin never persisted it).
409 — body name/country does not match the reserved claim.
502 — cs-api reported a terminal failure writing the pin.
503 — write path disabled, or cs-api transiently unavailable.

Responses

202Successful Response
422Validation Error

POST /api/v1/signup/complete

curl -X POST 'https://api.example.com/api/v1/signup/complete' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "string",
  "name": "string",
  "country_code": "string",
  "lat": 0.0,
  "lng": 0.0,
  "structured_address": {
    "address_road": "string",
    "address_house": "string",
    "address_house_number": "string",
    "address_addition": "string",
    "address_settlement": "string",
    "address_settlement_part": "string",
    "address_postcode": "string",
    "address_region": "string",
    "address_region_part": "string",
    "address_contact_name": "string"
  },
  "account_oauth_uid": "string",
  "verified_identifier": "string"
}'

import httpx

resp = httpx.post(
    "https://api.example.com/api/v1/signup/complete",
    headers={"Authorization": "Bearer ", "Content-Type": "application/json"},
    json={"token": "string", "name": "string", "country_code": "string", "lat": 0.0, "lng": 0.0, "structured_address": {"address_road": "string", "address_house": "string", "address_house_number": "string", "address_addition": "string", "address_settlement": "string", "address_settlement_part": "string", "address_postcode": "string", "address_region": "string", "address_region_part": "string", "address_contact_name": "string"}, "account_oauth_uid": "string", "verified_identifier": "string"},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.example.com/api/v1/signup/complete", {
  method: "POST",
  headers: { "Authorization": "Bearer ", "Content-Type": "application/json" },
  body: JSON.stringify({"token": "string", "name": "string", "country_code": "string", "lat": 0.0, "lng": 0.0, "structured_address": {"address_road": "string", "address_house": "string", "address_house_number": "string", "address_addition": "string", "address_settlement": "string", "address_settlement_part": "string", "address_postcode": "string", "address_region": "string", "address_region_part": "string", "address_contact_name": "string"}, "account_oauth_uid": "string", "verified_identifier": "string"})
});
const data = await resp.json();
console.log(data);

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"token": "string", "name": "string", "country_code": "string", "lat": 0.0, "lng": 0.0, "structured_address": {"address_road": "string", "address_house": "string", "address_house_number": "string", "address_addition": "string", "address_settlement": "string", "address_settlement_part": "string", "address_postcode": "string", "address_region": "string", "address_region_part": "string", "address_contact_name": "string"}, "account_oauth_uid": "string", "verified_identifier": "string"}`)
	req, _ := http.NewRequest("POST", "https://api.example.com/api/v1/signup/complete", body)
	req.Header.Set("Authorization", "Bearer ")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Request body

{"lat":0,"lng":0,"name":"string","token":"string","country_code":"string","account_oauth_uid":"string","structured_address":{"address_road":"string","address_house":"string","address_region":"string","address_addition":"string","address_postcode":"string","address_settlement":"string","address_region_part":"string","address_contact_name":"string","address_house_number":"string","address_settlement_part":"string"},"verified_identifier":"string"}