> For the complete documentation index, see [llms.txt](https://docs.bloq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloq.com/bloq-services/bloqstake/authenticate-to-bloq-api/api-routes.md).

# API Routes

Jump to:

* [POST /auth](#post-auth)
* [POST /users/{publicAddress}/nonce](#post-userspublicaddressnonce)

## POST /users/{publicAddress}/nonce

Get the Bloq API authentication nonce for the given user.

This nonce has to be signed with the private key corresponding to the Ethereum 1.0 address representing the user and sent in the request.

The signature must be then sent by calling `POST /auth` to get the authentication token and complete the authentication flow.

### Parameters

| Name          | In   | Type   | Required | Description                                                              |
| ------------- | ---- | ------ | -------- | ------------------------------------------------------------------------ |
| publicAddress | path | string | yes      | The Ethereum address of the user in lowercase or EIP-55 checksum format. |

#### Sample request

```shell
curl -X POST https://api.bloq.com/users/0x0000000000000000000000000000000000000000/nonce
```

### Response

| Status | Description                     |
| ------ | ------------------------------- |
| 200    | The user's nonce was retrieved. |
| 404    | The user was not found.         |

| Property | Type   | Description                      |
| -------- | ------ | -------------------------------- |
| nonce    | string | The user's authentication nonce. |

#### Sample response

```json
{
  "nonce": "Qd4b6cs9OUOEoXiSx"
}
```

## POST /auth

Authenticate to the Bloq API and obtain the token required to call the rest of the API routes.

After obtaining the nonce by calling `GET /users/{publicAddress}/nonce`, that nonce has to be signed with the private key corresponding to the user's Ethereum 1.0 address and sent back to the API to complete the authentication flow.

Once validated, the API will issue a short-lived JWT to be used as proof of authentication with the rest of the API routes.

### Parameters

| Name       | In   | Type   | Required | Description                                   |
| ---------- | ---- | ------ | -------- | --------------------------------------------- |
| .address   | body | string | yes      | The Ethereum 1.0 address of the signing user. |
| .service   | body | string | yes      | It must be 'stake'.                           |
| .signature | body | string | yes      | The signature of the message                  |
| .signedAt  | body | string | yes      | The ISO date of the moment of signing.        |

#### Sample request

```shell
curl -X POST https://api.bloq.com/auth \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "0x0000000000000000000000000000000000000000"
    "service": "stake",
    "signature": "0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "signedAt: "2022-07-11T18:23:22.513Z"
  }'
```

### Response

| Status | Description                             |
| ------ | --------------------------------------- |
| 200    | The authentication token was generated. |
| 401    | The user was not found.                 |
| 403    | The signature is invalid.               |

| Property | Type   | Description               |
| -------- | ------ | ------------------------- |
| (root)   | object | The response.             |
| .token   | string | The authentication token. |

#### Sample response

```json
{
  "token": "xxxxxx.xxxxxxxxxx.xxxxxx"
}
```