# 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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bloq.com/bloq-services/bloqstake/authenticate-to-bloq-api/api-routes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.