# v2

## Introduction

Bine API provides a SIWE (Sign In With Ethereum) authentication mechanism, allowing users to authenticate using their Ethereum wallets. This authentication method is secure, decentralized, and does away with traditional usernames and passwords.

{% hint style="warning" %}
Always ensure the safety of your Ethereum wallet's private keys. Never share them or expose them to any service.
{% endhint %}

## Prerequisites

Ensure you have an Ethereum wallet, such as MetaMask or WalletConnect.

## Login

{% hint style="info" %}
All other documentation (User API and Developer API) assumes that the user is authorized and the cookie is provided.
{% endhint %}

### Step 1: Retrieve the nonce

To initiate the authentication process, clients should first request a nonce value.

#### **Query**:

```graphql
query AuthNonce {
  authNonce {
    __typename
    ... on AuthNonceOk {
      result
    }
    ... on Error {
      message
    }
  }
}
```

#### **Response**:

```json
{
    "__typename": "NonceResponse"
    "result": "ghQwRYCzcpt"
}
```

Upon calling this query, the server will also set an `auth_token` cookie in the response. You should keep that cookie and send it in every GraphQL request.

#### **Errors:**

Two possible errors may occure:

{% code fullWidth="false" %}

```json
{
    "__typename": "AuthError"
    "message": "Invalid or expired session cookie"
}
```

{% endcode %}

{% code fullWidth="false" %}

```json
{
    "__typename": "AuthError"
    "message": "Already authenticated"
}
```

{% endcode %}

### Step 2: Sign the nonce using your Ethereum wallet

Once you have the nonce, use your Ethereum wallet to sign a message containing the nonce. The exact method will vary based on your wallet's interface. Check [Siwe Github Page ](https://github.com/spruceid/siwe)for more information. Example of the message object:

```json
{
    "domain": "app.bine.games",
    "address": "<address>",
    "statement": "Bine Games wants you to sign in with your wallet.",
    "uri": "https://app.bine.games",
    "version": "1",
    "chainId": 1,
    "nonce": "kjNBEqFTkPc",
    "issuedAt": "2023-08-09T11:48:36.694Z"
}
```

### Step 3: Send the signed message for verification

After signing the message, send both the message string and the signature to Bine API for verification.

**Mutation**:

```graphql
mutation Login($message: SiweMessageInput!, $signature: String!) {
  login(message: $message, signature: $signature) {
    __typename
    ... on LoginOk {
      result
    }
    ... on Error {
      message
    }
  }
}
```

**Variables:**

```json
{
    "message": {
        "domain": "app.bine.games",
        "address": "<address>",
        "statement": "Bine Games wants you to sign in with your wallet.",
        "uri": "app.bine.games",
        "version": "1",
        "chainId": 1,
        "nonce": "kjNBEqFTkPc",
        "issuedAt": "2023-08-09T11:48:36.694Z"
    },
    "signature": "<signature in hex>"
}
```

**Headers**:

```http
Cookie: auth_token=<your_cookie_value>
```

**Response:**

```json
{
    "__typename": "LoginOk",
    "result": "Logged in"
}
```

Additionally to success response, an auth\_token cookie will be provided in `Set-Cookie` response header. It should be set to `Cookie` response header. Read more on how HTTP cookies work [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies).

**Errors:**

Four possible errors may occure:

{% hint style="info" %}
Reason for Invalid signature could be:&#x20;

```
InvalidSignature
ExpiredMessage
NotYetValidMessage
DomainMismatch
NonceMismatch
```

{% endhint %}

```json
{
    "__typename": "ValidationError"
    "message": "Invalid signature (<reason>)"
}
```

{% code fullWidth="false" %}

```json
{
    "__typename": "ValidationError"
    "message": "Should provide a session cookie"
}
```

{% endcode %}

{% code fullWidth="false" %}

```json
{
    "__typename": "AuthError"
    "message": "Invalid or expired session cookie"
}
```

{% endcode %}

{% code fullWidth="false" %}

```json
{
    "__typename": "AuthError"
    "message": "Already authenticated"
}
```

{% endcode %}

## Logout

**Mutation**:

```graphql
mutation Logout {
  logout {
    __typename
    ... on LogoutOk {
      result
    }
    ... on Error {
      message
    }
  }
}
```

**Headers**:

```http
Cookie: auth_token=<your_cookie_value>
```

**Response:**

```json
{
    "__typename": "SiweLogoutOk",
    "result": "Logged out"
}
```

**Errors:**

Three possible errors may occure:

{% code fullWidth="false" %}

```json
{
    "__typename": "ValidationError"
    "message": "Should provide a session cookie"
}
```

{% endcode %}

{% code fullWidth="false" %}

```json
{
    "__typename": "AuthError"
    "message": "Invalid or expired session cookie"
}
```

{% endcode %}

{% code fullWidth="false" %}

```json
{
    "__typename": "AuthError"
    "message": "Not authenticated"
}
```

{% endcode %}

## Further Reading & Resources

* For a detailed understanding of SIWE, refer to the official [Sign In With Ethereum](https://login.xyz) documentation.
* Understanding Ethereum message signing: [Ethereum Message Signature](https://eips.ethereum.org/EIPS/eip-191).
* MetaMask's official guide on [Signing Data](https://docs.metamask.io/guide/signing-data.html).


---

# 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.bine.games/graphql/auth-api/v2.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.