Enter a verification code
POST /fapi/v1/verifications/{verification_id}:attempt · called from the environment's sign-in host
Checks the 6-digit code the user received after Send a verification code. A right code marks the address verified and uses up the code; the answer is 204. A wrong code uses up one of the code's attempts. A wrong, expired, used or exhausted code, an unknown id and another user's id all give the same 422 verification_invalid answer; in that case the user asks for a new code. Requires the authenticated user's __Host-idp_session cookie; if the cookie is missing, expired, or revoked, returns 401 unauthenticated. A first-party app on another origin can instead send its front API access token (Authorization: DPoP <token> with a DPoP proof; see Front API access token).
Request
Path parameter:
| Parameter | Description |
|---|---|
verification_id |
The id from the send answer. |
Headers:
| Header | Required | Description |
|---|---|---|
Idp-Client |
yes | SDK identifier. |
Origin |
yes | Must be exactly https://<sign-in host>. |
Content-Type |
yes | application/json. |
Body:
| Field | Type | Required | Description |
|---|---|---|---|
code |
string | yes | The 6-digit code from the email. |
Response
204 No Content; the address is verified.
Errors
| Status | Code | When |
|---|---|---|
| 400 | malformed_request |
The body is not valid JSON. |
| 400 | unknown_field |
The body has a field other than code. |
| 401 | unauthenticated |
No valid session cookie. |
| 403 | origin_not_allowed |
Origin is missing or wrong. |
| 403 | test_feature_not_in_production |
The code is the fixed test code 424242 and the environment is production. The attempt is used up like a wrong code. |
| 413 | payload_too_large |
The body is too large. |
| 415 | unsupported_media_type |
Content-Type is not application/json. |
| 422 | validation_failed |
code is missing. |
| 422 | verification_invalid |
The code is wrong, expired, used, or out of attempts, or the id is unknown. |
Example
curl -X POST https://example.keenauth.app/fapi/v1/verifications/0190a5c4-1b2c-7d3e-8f40-5162738400ff:attempt \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"code": "123456"}'