> For the complete documentation index, see [llms.txt](https://docs.ruuvi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ruuvi.com/communicate-with-ruuvi-cloud/cloud/user-api/register-user.md).

# Register User

User registration and verification

## Register a new user or create new access token for existing user

> Requests a verification code to be emailed.  The verification code is then entered to /verify to get the access token. The code is single-use and valid for 60 minutes. To protect against spam, this endpoint is rate limited.<br>

```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Register-User","description":"User registration and verification"}],"servers":[{"url":"https://network.ruuvi.com"},{"url":"https://testnet.ruuvi.com"}],"security":[],"paths":{"/register":{"post":{"summary":"Register a new user or create new access token for existing user","description":"Requests a verification code to be emailed.  The verification code is then entered to /verify to get the access token. The code is single-use and valid for 60 minutes. To protect against spam, this endpoint is rate limited.\n","operationId":"registerUser","tags":["Register-User"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Verification code emailed successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/registerResult"}}}]}}}},"400":{"description":"INVALID - Missing or malformed fields   Email missing or not valid format\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests - Rate limit exceeded Rate limits apply per email address, IP address and total.  Try again later.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Success":{"type":"object","required":["result","data"],"properties":{"result":{"type":"string","enum":["success"]},"data":{"description":"Endpoint-specific payload"}}},"registerResult":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email registered"}}},"Error":{"type":"object","required":["result","error","code"],"properties":{"result":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable explanation"},"code":{"type":"string","description":"Machine-readable primary error code"},"sub_code":{"nullable":true,"type":"string","description":"Optional secondary code useful for client logic"}}}}}}
```

## Verify a user's email with a verification code to get an access token

> Verify a user's email with the verification code emailed by \`POST /register\` to get an access token.\
> The code is single-use and valid for 60 minutes.\
> Access tokens remain valid while actively used and are\
> removed after approximately 180 days of inactivity, unless revoked earlier.\
> \
> Send the \`email\` the code was requested for. The code is then accepted only for that email,\
> and wrong codes are limited per email. Requests without \`email\` are still accepted for now,\
> but \`email\` will become required.\
> \
> When the code cannot be used, \`code\` is \`ER\_TOKEN\_EXPIRED\` and \`sub\_code\` tells why (see 403).<br>

```json
{"openapi":"3.0.3","info":{"title":"Ruuvi Cloud - User API","version":"1.0.0"},"tags":[{"name":"Register-User","description":"User registration and verification"}],"servers":[{"url":"https://network.ruuvi.com"},{"url":"https://testnet.ruuvi.com"}],"security":[],"paths":{"/verify":{"get":{"summary":"Verify a user's email with a verification code to get an access token","description":"Verify a user's email with the verification code emailed by `POST /register` to get an access token.\nThe code is single-use and valid for 60 minutes.\nAccess tokens remain valid while actively used and are\nremoved after approximately 180 days of inactivity, unless revoked earlier.\n\nSend the `email` the code was requested for. The code is then accepted only for that email,\nand wrong codes are limited per email. Requests without `email` are still accepted for now,\nbut `email` will become required.\n\nWhen the code cannot be used, `code` is `ER_TOKEN_EXPIRED` and `sub_code` tells why (see 403).\n","operationId":"verifyUser","tags":["Register-User"],"parameters":[{"name":"token","in":"query","required":true,"description":"The verification code from the email, currently 4 letters and digits. Letter case does not matter.\n","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"The email address the code was requested for. Letter case does not matter. Recommended now; it will become required.\n","schema":{"type":"string","format":"email"}}],"responses":{"200":{"description":"Verification code successful","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Success"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/verifyResult"}}}]}}}},"400":{"description":"`email` is malformed. Once `email` becomes required, this is also returned when it is missing.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`token` is missing or empty, or the server could not verify the code (for example after a server key change). Request a new code.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The code cannot be used. `code` is always `ER_TOKEN_EXPIRED`; `sub_code` tells why:\n\n- `ER_SUB_INVALID_CODE`: the code is wrong or malformed, or it was requested for a different\n  email than `email`. Check the code and try again. With `email`, this counts towards the\n  wrong-code limit (see 429).\n- `ER_SUB_CODE_USED`: the code has already been used. Request a new code.\n- `ER_SUB_CODE_EXPIRED`: the code has expired. Request a new code.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many attempts. `code` is `ER_THROTTLED`.\n\n- Without `sub_code`: more than 30 attempts from your IP address within 15 minutes.\n  Try again in a few minutes.\n- `ER_SUB_TOO_MANY_ATTEMPTS`: 5 wrong codes for `email`. All codes for that email,\n  including the right one, are refused until 15 minutes after the last wrong code.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error. Try again; if the code is then reported as already used (`ER_SUB_CODE_USED`), request a new code.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Success":{"type":"object","required":["result","data"],"properties":{"result":{"type":"string","enum":["success"]},"data":{"description":"Endpoint-specific payload"}}},"verifyResult":{"type":"object","required":["email","accessToken","newUser"],"properties":{"email":{"type":"string","format":"email","description":"Email verified"},"accessToken":{"type":"string","description":"Access token for the verified user"},"newUser":{"type":"boolean","description":"Indicates if the user is new"}}},"Error":{"type":"object","required":["result","error","code"],"properties":{"result":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable explanation"},"code":{"type":"string","description":"Machine-readable primary error code"},"sub_code":{"nullable":true,"type":"string","description":"Optional secondary code useful for client logic"}}}}}}
```
