# Account Recovery (SEP-10 / SEP-30) (https://dev.cosmospay.lat/docs/api/recovery/)

> Served by the two recovery deployments only. Standard SEP-10 web authentication and SEP-30 account recovery: each server holds half of what a recovery signature needs, and proves the person’s inbox on its own.

Base URL: `https://api.cosmospay.lat/cosmos-api`

## SEP-1 discovery for this recovery server

`GET /.well-known/stellar.toml`

WEB_AUTH_ENDPOINT and SIGNING_KEY (SEP-10), HOME_DOMAIN, and a [[RECOVERY_SERVERS]] entry with the SEP-30 ENDPOINT, the ROLE and the identity methods. 404 on a deployment that is not a recovery server.

No authentication.

**Query parameters**

- `network` (string, optional): The ledger the file describes, `public` or `testnet`: its SEP-10 and SEP-30 endpoints then carry that ledger as a path segment. Omit for the deployment default. Any other value, or a ledger not in RECOVERY_NETWORKS, is a 404.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `500`: InternalError (see Shared responses)

## A challenge for an account

`GET /v1/sep10/auth`

Public: no API key. Answers a SEP-10 challenge transaction for `account` (a `G...` address) with the `network_passphrase` to sign it for; sign it with the account and exchange it at `POST /v1/sep10/auth`. Sequence 0: unsubmittable by construction. Errors have the SEP body `{ "error": "..." }`; a deployment that is not a recovery server answers 404.

No authentication.

**Query parameters**

- `account` (string, required): The Stellar account (G…) to authenticate.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Exchange a signed challenge for a token

`POST /v1/sep10/auth`

Weighed against the account's CURRENT signers and medium threshold, so a recovered account authenticates with the key that replaced its master.

No authentication.

**Request body** (`application/json`, required): `Sep10TokenDto`

- `transaction` (string, required): The challenge, signed by the account.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)

## Exchange an OIDC ID token for this server's identity token

`POST /v1/sep30/identity`

SEP-30 "external" authentication. The ID token is verified against the provider's published keys, must stand for a login in the last 15 minutes, must carry a VERIFIED email, and is accepted once per server.

No authentication.

**Request body** (`application/json`, required): `RecoveryIdTokenDto`

- `id_token` (string, required): An OIDC ID token from the provider this server names as OIDC_ISSUER in its stellar.toml. Accepted once per server.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Email a code that proves an inbox to this server

`POST /v1/sep30/identity/email/start`

The same answer whether or not the address recovers anything here; a code is only sent to one that does.

No authentication.

**Request body** (`application/json`, required): `RecoveryEmailStartDto`

- `email` (string, required): The inbox to prove.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Answer an emailed code

`POST /v1/sep30/identity/email/verify`

Public: no API key. Send the `claim_token` from `POST /v1/sep30/identity/email/start` with the emailed `code`: the right answer is `status: ready` with this server's identity token for that inbox, once; a wrong one is `invalid` with `attempts_left`, and an unknown, used or lapsed claim is `expired`. Five wrong answers burn it (`locked`).

No authentication.

**Request body** (`application/json`, required): `RecoveryEmailVerifyDto`

- `claim_token` (string, required): The `claim_token` from `POST /v1/sep30/identity/email/start` (base64url).
- `code` (string, required): The six digits emailed.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Accounts this caller may recover (paged by `after`)

`GET /v1/sep30/accounts`

A SEP-10 token lists its own account when it is registered here; this server's identity token for an email lists every account naming that email. It reads one ledger (the one the path names, e.g. `/v1/sep30/testnet/accounts`, or the default) and answers up to 100 accounts per page in address order as `{ accounts }`; pass the last address as `after` for the next page. Errors have the SEP body `{ "error": "..." }`: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

**Query parameters**

- `after` (string, optional): The last address of the previous page.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Describe an account

`GET /v1/sep30/accounts/{address}`

The account's identity roles, flagging the one the token authenticates as, and this server's signer key for it. Takes the account's SEP-10 token, or this server's identity token for an email registered on it; an account that is absent and one the token may not act on are the same 404. Errors have the SEP body `{ "error": "..." }`: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

**Responses**

- `200`: OK
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Register an account (SEP-10 token of that account)

`POST /v1/sep30/accounts/{address}`

Stores who may recover `address` (1 to 3 identities, roles `owner`, `sender` or `receiver`, each with 1 to 3 `email` auth methods) and answers the account with `signers`: this server's key for it. Only a SEP-10 token of that same account may call it (403 otherwise), and an account already registered here is a 409: change it with `PUT`. Errors have the SEP body `{ "error": "..." }`: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

**Request body** (`application/json`, required): `Sep30IdentitiesDto`

- `identities` (IdentityDto[], required): The account's identities.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Replace who may recover an account (SEP-10 token of that account)

`PUT /v1/sep30/accounts/{address}`

Replaces the identities of `address`, never merging them with the old ones, and registers the account if it is not here yet. Only a SEP-10 token of that same account may call it (403 otherwise); it answers the account as `POST` does. Errors have the SEP body `{ "error": "..." }`: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

**Request body** (`application/json`, required): `Sep30IdentitiesDto`

- `identities` (IdentityDto[], required): The account's identities.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Forget an account (SEP-10 token of that account)

`DELETE /v1/sep30/accounts/{address}`

Deletes the registration and its identities and answers the account as it was. Only a SEP-10 token of that same account may call it (403 otherwise); an account not registered here is a 404. Errors have the SEP body `{ "error": "..." }`: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

**Responses**

- `200`: OK
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Co-sign a recovery transaction

`POST /v1/sep30/accounts/{address}/sign/{signer}`

Returns the SIGNATURE, not an envelope. Only an account-control change on the registered account, sourced by it, with no memo, valid for at most 15 minutes.

**Request body** (`application/json`, required): `Sep30SignDto`

- `transaction` (string, required): The transaction to co-sign, base64 XDR.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Every half this server holds for the proven inbox (paged by `after`)

`GET /v1/sep30/shares`

This server's identity token for an email. One proof brings back the halves of every wallet backed up under it.

**Query parameters**

- `after` (string, optional): The last address of the previous page.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Take this server's half back (the account's key, or its proven inbox)

`GET /v1/sep30/shares/{address}`

The account's SEP-10 token, or this server's identity token for the email the half was filed under. Absent and not-yours are the same 404.

**Responses**

- `200`: OK
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## File this server's half of a backup's recovery key (SEP-10 token of that account)

`PUT /v1/sep30/shares/{address}`

Replaces any half filed before: a re-sealed backup has a new key. The email is who may take the half back.

**Request body** (`application/json`, required): `RecoveryShareDto`

- `share` (string, required): This server's half of the backup's recovery key: 32 random-looking bytes, base64. Useless without the other server's half.
- `email` (string, required): The inbox that may take the half back, proven to THIS server with its identity token.

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Forget this server's half (SEP-10 token of that account)

`DELETE /v1/sep30/shares/{address}`

Deletes this server's half of the backup recovery key filed for `address` and answers `{ address }`. Only a SEP-10 token of that same account may call it (403 otherwise); no half filed here is a 404. Errors have the SEP body `{ "error": "..." }`: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

**Responses**

- `200`: OK
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Shared responses

- **ValidationFailed** (`ApiErrorBodyEntity`): The body, query or path failed validation. `message` is an array of the individual failures. Routes that reject a *valid* request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
  - `statusCode` (number, required): Always the HTTP status of the response itself.
  - `code` (string, required): Stable machine-readable code. Branch on this, never on the message: messages are human-facing and may be reworded; codes are never renamed once published. Each response documents the subset it can return. One of: `insufficient_scope`, `no_authenticated_consumer`, `gateway_required`, `admin_console_only`, `not_found`, `validation_failed`, `payload_too_large`, `idempotency_conflict`, `operation_in_flight`, `invalid_state_transition`, `slippage_exceeded`, `insufficient_balance`, `no_path_found`, `trustline_missing`, `invalid_amount`, `invalid_memo`, `transaction_rejected`, `transaction_already_settled`, `recipient_not_registered`, `payment_transfer_mismatch`, `fee_transfer_mismatch`, `merchant_fee_transfer_mismatch`, `payer_mismatch`, `transaction_not_found`, `expired`, `network_unsupported`, `asset_unsupported`, `merchant_fee_unsupported`, `provider_error`, `provider_unavailable`, `quote_not_found`, `quote_expired`, `kyc_state_invalid`, `kyc_review_required`, `account_disabled`, `payload_expired`, `rate_limited`, `customer_wallet_taken`, `alias_taken`, `alias_name_invalid`, `alias_challenge_invalid`, `alias_signature_invalid`, `alias_recovery_invalid`, `alias_address_conflict`, `wallet_handshake_invalid`, `wallet_verifier_invalid`, `wallet_login_code_invalid`, `wallet_login_code_cooldown`, `wallet_session_invalid`, `wallet_signature_invalid`, `wallet_backup_invalid`, `wallet_backup_limit`, `wallet_account_mismatch`, `wallet_provider_unavailable`, `wallet_return_url_not_allowed`, `wallet_recovery_setup_refused`, `easy_recovery_not_found`, `easy_recovery_already_offered`, `easy_recovery_not_offered`, `easy_recovery_code_invalid`, `easy_recovery_burned`, `plugin_not_installed`, `plugin_consent_mismatch`, `plugin_rejected`, `plugin_quota_exceeded`, `plugin_failed`, `protected_payment_buyer_mismatch`, `protected_payment_signature_invalid`, `misconfigured`, `internal_error`.
  - `error` (string, required): The HTTP reason phrase for `statusCode`.
  - `message` (string | string[], required): Human-readable detail. An array when class-validator rejected the body.
  - `details` (object, optional): Machine-readable facts about this failure, present only on the codes whose example shows it: `easy_recovery_code_invalid` carries `{ "attemptsLeft": 4 }`. Absent everywhere else.
  - `path` (string, required): The path of the request that failed.
  - `timestamp` (string, required): When the envelope was produced, ISO 8601.
- **InternalError** (`ApiErrorBodyEntity`): Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
- **RateLimited** (`ApiErrorBodyEntity`): The budget in `x-cosmos-rate-limit` is spent for this caller. Honour `Retry-After`. The `ratelimit-*` triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers `503 provider_unavailable`.
- **UpstreamUnavailable** (`ApiErrorBodyEntity`): `provider_unavailable`: the provider in `x-cosmos-upstream` is down or unreachable; the message names it. Retry. `misconfigured`: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
- **NotFound** (`ApiErrorBodyEntity`): No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
