This API implements the SEP-30 protocol. Enables an individual (e.g., a user or wallet) to regain access to a Stellar account that it owns after the individual has lost its private key without providing any third-party control of the account.
Account Recovery API provides two custom endpoints to authenticate externally using the authentication methods defined by the server, one to request a verification code, and another to send it and receive a JWT in return.
It also provides the required endpoints in the SEP-30 and the SEP-10 documentation.
Defined by the implementer, for now, the supported methods are:
Type | Description |
---|---|
phone_number |
A phone number. When encoding a phone number the ITU-T recommendations E.123 and E.164 should be followed. The phone number should be formatted in international notation with a leading + as demonstrated in E.123 Section 2.5 to ensure phone numbers are consistently encoded and are globally unique. Spaces should be omitted. |
email |
An email address. |
This endpoint requests a verification code for a registered account.
The user that wants to recover an account, should send the authorization method and value for the account previously registered in the SEP-30 endpoint POST /accounts/<address>
. It is necessary to send only one of the auth_methods
that has been registered.
Request Parameters:
Name | Type | Description |
---|---|---|
type |
string | Auth method type defined in External authentication methods, one of the auth_methods previously registered in the POST /accounts/ endpoint. |
value |
string | One of the auth values previously registered in the POST /accounts/ endpoint, with which the user wants to receive the verification code. |
Example:
POST https://server-url/api/external-auth/verification/GCQKGUIQ56DQYFY7S7HYBRX6JLOS56FXSDEWRGAEPDHF7BJR3HTXC24G
{
"type": "email",
"value": "john-titor@test.com"
}
200
This endpoint sends to the server the verification code received when the user made a request in the previous endpoint. In response, if the request is successful, the user will get a JWT that he could use to access the required endpoints, authenticated as one of the identities that can control the registered account.
Request Parameters:
Name | Type | Description |
---|---|---|
type |
string | Auth method type defined in External authentication methods, one of the auth values previously registered in the POST /accounts/ endpoint. |
value |
string | One of the auth values previously registered in the POST /accounts/ endpoint, with which the user wants to receive the verification code. |
verification_code |
string | Verification code received in the auth_method requested in the POST api/external-auth/verification/ |
Example:
POST https://server-url/api/external-auth/authentication/GCQKGUIQ56DQYFY7S7HYBRX6JLOS56FXSDEWRGAEPDHF7BJR3HTXC24G
{
"type": "email",
"value": "john-titor@test.com",
"verification_code": "98400"
}
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC..."
}
If an error occurs when calling any endpoint, an appropriate HTTP status code will be returned along with an error response.
Common HTTP status codes may be returned for a server. In particular the following are expected:
Status Code | Name | Reason |
---|---|---|
400 |
Bad Request | The request is invalid in any way. |
401 |
Unauthorized | No Authorization header has been provided or the contents of the header are not accepted as valid. |
404 |
Not Found | The validation code or the validation method is invalid. |
429 |
Too many requests | There were too many attempts to validate the verification code. |
For further information, please refer to the SEP-30 documentation.
POST /accounts/<address>
requiredSEP-10
JWTPUT /accounts/<address>
requiredexternal-auth
JWTPOST /accounts/<address>/sign/<signing-address>
requiredexternal-auth
JWT *GET /accounts/<address>
requiredSEP-10
JWTDELETE /accounts/<address>
requiredexternal-auth
JWTGET /accounts
requiredSEP-10
JWT
In the case of POST /accounts/<address>/sign/<signing-address>
, we use the simple approach as it is detailed in the SEP-30 documentation:
The simplest approach is to require the transaction to only contain operations for the authenticated account. The server can verify that the source account of the transaction and the source account of all operations in the transaction match the account in the request [ ... ]
The transaction can contain any operations, but it is anticipated for the use cases discussed earlier in this protocol that the transaction will contain an operation to add a new signer to the account and possibly to remove an old signer or to merge an account. The signature will be generated using the signing key that the server generated during registration for the account.
For further information, please refer to the SEP-10 documentation.
GET <WEB_AUTH_ENDPOINT>
POST <WEB_AUTH_ENDPOINT>