Account Recovery (SEP-10 / SEP-30)
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.
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.
network?stringThe 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.
OK
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/.well-known/stellar.toml'"string"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.
account*stringThe Stellar account (G…) to authenticate.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/sep10/auth?account=string'Weighed against the account's CURRENT signers and medium threshold, so a recovered account authenticates with the key that replaced its master.
application/json- body
SEP-10: the signed challenge transaction, exchanged for a token of that account.
transaction*stringThe challenge, signed by the account.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
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.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep10/auth' \ -H 'Content-Type: application/json' \ -d '{ "transaction": "string"}'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.
application/json- body
Proves an inbox to this recovery server with an OIDC ID token.
id_token*stringAn OIDC ID token from the provider this server names as OIDC_ISSUER in its stellar.toml. Accepted once per server.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep30/identity' \ -H 'Content-Type: application/json' \ -d '{ "id_token": "string"}'The same answer whether or not the address recovers anything here; a code is only sent to one that does.
application/json- body
Asks this recovery server to email a code that proves an inbox.
email*stringThe inbox to prove.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep30/identity/email/start' \ -H 'Content-Type: application/json' \ -d '{ "email": "person@example.com"}'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).
application/json- body
Answers the code this recovery server emailed.
claim_token*stringThe claim_token from POST /v1/sep30/identity/email/start (base64url).
code*stringThe six digits emailed.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep30/identity/email/verify' \ -H 'Content-Type: application/json' \ -d '{ "claim_token": "string", "code": "123456"}'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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
after?stringThe last address of the previous page.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts'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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
application/json- body
SEP-30: the identities that may recover an account.
identities*array<>The account's identities.
OK
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.
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts/{address}' \ -H 'Content-Type: application/json' \ -d '{ "identities": [ { "role": "owner", "auth_methods": [ { "type": "email", "value": "person@example.com" } ] } ]}'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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
application/json- body
SEP-30: the identities that may recover an account.
identities*array<>The account's identities.
OK
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.
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X PUT 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts/{address}' \ -H 'Content-Type: application/json' \ -d '{ "identities": [ { "role": "owner", "auth_methods": [ { "type": "email", "value": "person@example.com" } ] } ]}'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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
application/json- body
SEP-30: a transaction for this server to co-sign for a recovered account.
transaction*stringThe transaction to co-sign, base64 XDR.
OK
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.
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts/{address}/sign/{signer}' \ -H 'Content-Type: application/json' \ -d '{ "transaction": "string"}'This server's identity token for an email. One proof brings back the halves of every wallet backed up under it.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
after?stringThe last address of the previous page.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/sep30/shares'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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
OK
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/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.
sep-tokenAuthorizationBearer <JWT>A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.
application/json- body
This server's half of a wallet backup's recovery key, filed under the inbox that may take it back.
share*stringThis server's half of the backup's recovery key: 32 random-looking bytes, base64. Useless without the other server's half.
email*stringThe inbox that may take the half back, proven to THIS server with its identity token.
OK
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.
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.
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.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X PUT 'https://api.cosmospay.lat/cosmos-api/v1/sep30/shares/{address}' \ -H 'Content-Type: application/json' \ -d '{ "share": "q83vEjRWeJCrze8SNFZ4kKvN7xI0VniQq83vEjRWeJA=", "email": "person@example.com"}'Wallet Sign-in
The Cosmos Pay Wallet’s own sign-in: Authentik (OpenID Connect), Google, GitHub or an emailed code. It proves who a person is and never touches a key; the seed backup it stores is sealed on the device under a password this service never sees.
Wallet Easy Recovery
Move a wallet between two devices through a five-minute mailbox this service cannot open.